docs(cli): document personal-vs-team cloud sync semantics (#947)

Folds in the intent of #857 reconciled with the post-#920 push/pull reality. Closes #851.

Co-authored-by: Drew Cain <groksrc@users.noreply.github.com>
Signed-off-by: phernandez <paul@basicmemory.com>

docs/cloud-cli.md

@@ -318,7 +318,7 @@ For MCP stdio, routing is always local.
 | `bm cloud push` | local → cloud | Personal + Team | Upload local changes, additively (git-style) |
 | `bm cloud sync` | local → cloud | Personal only | One-way mirror (cloud becomes identical to local) |
 | `bm cloud bisync` | local ↔ cloud | Personal only | Two-way mirror (recommended for solo use) |
-| `bm cloud check` | — | Personal + Team | Verify files match (no changes) |
+| `bm cloud check` | — | Personal only | Verify mirror integrity (no changes) |
 
 If you collaborate on a shared Team workspace, use **`push`/`pull`** (see [Team Workspaces](#team-workspaces-push--pull-additive-git-style)). If you are the only writer (a Personal workspace), the mirror commands `sync`/`bisync` give you a single source of truth.
 
@@ -459,10 +459,12 @@ bm cloud bisync --name research
 - You edit in multiple places
 - You want automatic conflict resolution
 
-### Verify Sync Integrity
+### Verify Sync Integrity (Personal only)
 
 **Use case:** Check if local and cloud match without making changes.
 
+> **Personal workspaces only.** `check` compares against the Personal workspace mirror remote, like `sync`/`bisync`. On Team workspaces use `bm cloud pull --dry-run` / `bm cloud push --dry-run` to preview differences instead.
+
 ```bash
 bm cloud check --name research
 ```
@@ -999,7 +1001,7 @@ bm cloud bisync --name <project> --resync # First time / force baseline
 bm cloud bisync --name <project> --dry-run
 bm cloud bisync --name <project> --verbose
 
-# Integrity check
+# Integrity check - Personal workspaces only
 bm cloud check --name <project>
 bm cloud check --name <project> --one-way
 

src/basic_memory/cli/commands/cloud/project_sync.py

@@ -512,7 +512,11 @@ def bisync_project_command(
     resync: bool = typer.Option(False, "--resync", help="Force new baseline"),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
 ) -> None:
-    """Two-way sync: local <-> cloud (bidirectional sync).
+    """Two-way mirror: local <-> cloud (bidirectional sync).
+
+    Personal workspaces only. This mirror can delete and overwrite files on both
+    sides, so on Team workspaces use `bm cloud pull` (fetch) / `bm cloud push`
+    (additive upload) instead.
 
     Examples:
       bm cloud bisync --name research --resync  # First time
@@ -576,7 +580,11 @@ def check_project_command(
     name: str = typer.Option(..., "--name", "--project", help="Project name to check"),
     one_way: bool = typer.Option(False, "--one-way", help="Check one direction only (faster)"),
 ) -> None:
-    """Verify file integrity between local and cloud.
+    """Verify file integrity between local and cloud (no changes made).
+
+    Personal workspaces only: check compares against the Personal workspace
+    mirror remote. On Team workspaces use `bm cloud pull --dry-run` /
+    `bm cloud push --dry-run` to preview differences instead.
 
     Example:
       bm cloud check --name research
@@ -624,6 +632,9 @@ def bisync_reset(
 ) -> None:
     """Clear bisync state for a project.
 
+    Personal workspaces only (bisync is a Personal-workspace mirror; on Team
+    workspaces use `bm cloud pull` / `bm cloud push` instead).
+
     This removes the bisync metadata files, forcing a fresh --resync on next bisync.
     Useful when bisync gets into an inconsistent state or when remote path changes.
     """

tests/cli/cloud/test_project_sync_command.py

@@ -15,6 +15,21 @@ from basic_memory.schemas.cloud import WorkspaceInfo
 runner = CliRunner()
 
 
+@pytest.mark.parametrize(
+    "command",
+    ["sync", "bisync", "check", "bisync-reset"],
+)
+def test_cloud_mirror_command_help_marks_personal_workspaces_only(command):
+    """Mirror-family help must say Personal-only and point Team users at push/pull (#851)."""
+    result = runner.invoke(app, ["cloud", command, "--help"])
+
+    assert result.exit_code == 0, result.output
+    output = " ".join(result.output.split())
+    assert "Personal workspaces only" in output
+    assert "bm cloud pull" in output
+    assert "bm cloud push" in output
+
+
 @pytest.mark.parametrize(
     "argv",
     [