forest-cli 0.1.0__py3-none-any.whl

forest/cli.py

@@ -0,0 +1,2747 @@
+"""Click CLI for forest."""
+
+from __future__ import annotations
+
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import partial
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+import click
+
+from forest import __version__, analytics, metrics, monitoring
+from forest import rclone as _rclone
+from forest.checkout import (
+    RESERVED_CHECKOUT_NAMES,
+    RESERVED_REMOTE_NAMES,
+    CheckoutError,
+    WorkspaceConfig,
+    adopt_checkout,
+    checkout_dir,
+    checkout_lock,
+    checkout_metadata_paths,
+    create_checkout,
+    ensure_registry_gitignore,
+    ensure_workspace_gitignore,
+    find_project_boundary,
+    find_workspace_root,
+    list_checkouts,
+    load_workspace_config,
+    normalize_workspace_path,
+    read_head,
+    remote_url_has_secret_material,
+    require_registered_checkout,
+    resolve_active_config,
+    save_workspace_config,
+    switch_checkout,
+    validate_token,
+    validate_workspace_data_path,
+)
+from forest.checkout import (
+    remove_checkout as remove_checkout_metadata,
+)
+from forest.config import (
+    ConfigError,
+    LocalConfig,
+    ProjectConfig,
+    RemoteConfig,
+    StageConfig,
+    load_config,
+    load_local_config_file,
+    save_config,
+    save_local_config_file,
+)
+from forest.flow import build_graph, render_mermaid
+from forest.fsutil import atomic_write
+from forest.logger import configure_logging, get_logger, new_run_id
+from forest.manifest import ManifestError, load_manifest
+from forest.paths import (
+    _effective_remote_base,
+    discover_units,
+    list_sync_files,
+    resolve_manifest_pairs,
+    resolve_paths,
+)
+from forest.rclone import (
+    RCLONE_INSTALL_MSG,
+    RcloneError,
+    RcloneTransport,
+    RemoteFile,
+    TransferResult,
+    build_remote,
+    get_transport,
+)
+from forest.sync_state import SyncEntry, SyncState, compute_checksum, load_state, record_pull, record_push, save_state
+
+_log = get_logger("forest.cli")
+
+
+def is_available() -> bool:
+    """Return live rclone availability, keeping CLI gates monkeypatch-safe."""
+    return _rclone.is_available()
+
+
+class ForestGroup(click.Group):
+    """Custom group that catches unhandled exceptions and formats them."""
+
+    def invoke(self, ctx: click.Context) -> None:
+        # ctx.invoked_subcommand is only set once Click resolves the subcommand
+        # inside super().invoke(), so read it at use time, not up front.
+        start = time.monotonic()
+        status = "error"
+        try:
+            super().invoke(ctx)
+            status = "success"
+        except click.exceptions.Exit as exc:
+            if exc.exit_code == 0:
+                status = "success"
+            raise
+        except (click.Abort, click.ClickException):
+            raise
+        except Exception as exc:
+            monitoring.report_failure(
+                "unhandled command error",
+                str(exc),
+                command=ctx.invoked_subcommand or "forest",
+                exc=exc,
+            )
+            click.echo(f"Error: {exc}", err=True)
+            ctx.exit(1)
+        finally:
+            analytics.record_command(
+                ctx.invoked_subcommand or "forest",
+                duration_seconds=time.monotonic() - start,
+                status=status,
+            )
+
+
+def _echo_info(ctx: click.Context, msg: str) -> None:
+    """Echo to stdout. Suppressed by --quiet."""
+    if not ctx.obj.get("quiet"):
+        click.echo(msg)
+
+
+def _echo_verbose(ctx: click.Context, msg: str) -> None:
+    """Echo verbose details to stdout. Only with --verbose, suppressed by --quiet."""
+    if ctx.obj.get("verbose") and not ctx.obj.get("quiet"):
+        click.echo(msg)
+
+
+def _echo_error(msg: str) -> None:
+    """Echo to stderr. Never suppressed."""
+    click.echo(msg, err=True)
+
+
+def _transport_error_detail(exc: Exception) -> str:
+    """Return user-facing transport failure detail without losing rclone stderr."""
+    if isinstance(exc, RcloneError):
+        return (exc.stderr or str(exc)).strip()
+    return str(exc)
+
+
+def _preflight_remote_config(ctx: click.Context, remote_cfg: RemoteConfig) -> bool:
+    """Validate transport config before any rclone network operation."""
+    try:
+        build_remote(remote_cfg)
+    except ValueError as exc:
+        _echo_error(f"Error: {exc}")
+        ctx.exit(1)
+        return False
+    return True
+
+
+@click.group(cls=ForestGroup, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, prog_name="forest")
+@click.option("-C", "chdir", default=None, type=click.Path(path_type=Path), help="Run as if started in PATH.")
+@click.option("--verbose", is_flag=True, help="Enable detailed output.")
+@click.option("--quiet", is_flag=True, help="Suppress all output except errors.")
+@click.pass_context
+def main(ctx: click.Context, chdir: Path | None, verbose: bool, quiet: bool) -> None:
+    """git-like data management for arbitrary data trees."""
+    if verbose and quiet:
+        raise click.UsageError("--verbose and --quiet are mutually exclusive.")
+    ctx.ensure_object(dict)
+    discovery_cwd = Path.cwd()
+    if chdir is not None:
+        discovery_cwd = chdir if chdir.is_absolute() else discovery_cwd / chdir
+        if not discovery_cwd.exists():
+            raise click.BadParameter(f"path does not exist: {chdir}", param_hint="-C")
+        if not discovery_cwd.is_dir():
+            raise click.BadParameter(f"path is not a directory: {chdir}", param_hint="-C")
+    ctx.obj["cwd"] = discovery_cwd.resolve(strict=False)
+    ctx.obj["verbose"] = verbose
+    ctx.obj["quiet"] = quiet
+
+    # Observability: one trace ID per invocation, stamped on every log record,
+    # metric sample, and error/alert report (see forest.logger docs).
+    run_id = new_run_id()
+    configure_logging(verbose=verbose)
+    monitoring.init_error_tracking(command=ctx.invoked_subcommand or "forest")
+    _log.info(
+        "invocation",
+        extra={"command": ctx.invoked_subcommand or "", "argv": sys.argv[1:], "cwd": str(ctx.obj["cwd"])},
+    )
+    ctx.obj["run_id"] = run_id
+
+
+@dataclass
+class ProjectContext:
+    """Resolved active project context for CLI commands."""
+
+    config: ProjectConfig
+    data_root: Path
+    state_path: Path
+    config_path: Path
+    local_config_path: Path
+    mode: str
+    checkout_name: str | None = None
+
+
+def _handle_checkout_error(ctx: click.Context, exc: Exception) -> None:
+    msg = str(exc)
+    if "Ambiguous forest config" in msg:
+        _echo_error(f"Error: {msg}")
+        _echo_error("Remove one config, or run 'forest checkout adopt NAME' to migrate the legacy root config.")
+    elif msg.startswith("No active checkout"):
+        _echo_error("Error: no active checkout selected.")
+        _print_checkout_guidance(ctx, err=True)
+    else:
+        _echo_error(f"Error: {msg}")
+    ctx.exit(1)
+
+
+def _print_checkout_guidance(ctx: click.Context, *, err: bool = False) -> None:
+    start = Path(ctx.obj["cwd"])
+    try:
+        workspace_root = find_workspace_root(start)
+        names = sorted(load_workspace_config(workspace_root).checkouts) if workspace_root is not None else []
+    except CheckoutError:
+        names = []
+
+    echo = _echo_error if err else lambda message: _echo_info(ctx, message)
+    if names:
+        for name in names:
+            echo(f"Run: forest checkout {name}")
+    else:
+        echo("Run: forest checkout create NAME")
+
+
+def _get_project_context(ctx: click.Context) -> ProjectContext:
+    """Resolve and cache active config, data root, state path, and writable paths."""
+    cached = ctx.obj.get("project_context")
+    if isinstance(cached, ProjectContext):
+        return cached
+
+    start = Path(ctx.obj["cwd"])
+    try:
+        config, data_root, state_path = resolve_active_config(start)
+        workspace_config = data_root / ".forest" / "config.yaml"
+        if workspace_config.exists():
+            checkout_name = read_head(data_root)
+            registry = load_workspace_config(data_root)
+            if checkout_name not in registry.checkouts:
+                raise CheckoutError(f"Active checkout '{checkout_name}' is not registered in workspace config.")
+            active_dir = checkout_dir(data_root, checkout_name)
+            if not active_dir.is_dir():
+                raise CheckoutError(f"Active checkout '{checkout_name}' metadata directory is missing.")
+            project_context = ProjectContext(
+                config=config,
+                data_root=data_root,
+                state_path=state_path,
+                config_path=active_dir / "forest.yaml",
+                local_config_path=active_dir / "local.yaml",
+                mode="workspace",
+                checkout_name=checkout_name,
+            )
+        else:
+            project_context = ProjectContext(
+                config=config,
+                data_root=data_root,
+                state_path=state_path,
+                config_path=data_root / "forest.yaml",
+                local_config_path=data_root / ".forest" / "local.yaml",
+                mode="legacy",
+            )
+    except (CheckoutError, ConfigError) as exc:
+        _handle_checkout_error(ctx, exc)
+        raise AssertionError("unreachable") from exc
+
+    ctx.obj["project_context"] = project_context
+    ctx.obj["config"] = project_context.config
+    ctx.obj["data_root"] = project_context.data_root
+    ctx.obj["state_path"] = project_context.state_path
+    ctx.obj["config_path"] = project_context.config_path
+    return project_context
+
+
+def _load_project_config(ctx: click.Context) -> ProjectConfig:
+    """Return the active project config resolved from cwd or -C."""
+    return _get_project_context(ctx).config
+
+
+def _load_writable_project_config(ctx: click.Context) -> ProjectConfig:
+    """Load the shared config file that writers may safely save."""
+    project_context = _get_project_context(ctx)
+    if project_context.mode == "workspace":
+        try:
+            return load_config(project_context.config_path)
+        except ConfigError as exc:
+            _handle_checkout_error(ctx, exc)
+            raise AssertionError("unreachable") from exc
+    return project_context.config
+
+
+def _save_project_config(ctx: click.Context, config: ProjectConfig) -> None:
+    project_context = _get_project_context(ctx)
+    save_config(config, project_context.config_path, include_stage_paths=project_context.mode == "legacy")
+    project_context.config = config
+
+
+def _load_active_local_config(ctx: click.Context) -> LocalConfig:
+    project_context = _get_project_context(ctx)
+    try:
+        return load_local_config_file(project_context.local_config_path)
+    except ConfigError as exc:
+        _handle_checkout_error(ctx, exc)
+        raise AssertionError("unreachable") from exc
+
+
+def _save_active_local_config(ctx: click.Context, config: LocalConfig) -> None:
+    save_local_config_file(config, _get_project_context(ctx).local_config_path)
+
+
+def _project_root(ctx: click.Context) -> Path:
+    """Return the resolved data root."""
+    return _get_project_context(ctx).data_root
+
+
+def _state_path(ctx: click.Context) -> Path:
+    """Return the active sync state path."""
+    return _get_project_context(ctx).state_path
+
+
+def _ensure_stage_bound(ctx: click.Context, stage_name: str, stage_cfg: StageConfig) -> bool:
+    """Require a local stage binding before local file access."""
+    if stage_cfg.path is not None:
+        return True
+    _echo_error(f"Error: stage '{stage_name}' is not bound. Run: forest bind {stage_name} <PATH>")
+    ctx.exit(1)
+    return False
+
+
+def _required_stage_path(ctx: click.Context, stage_name: str, stage_cfg: StageConfig) -> Path:
+    """Return a stage path or exit with bind guidance."""
+    if stage_cfg.path is None:
+        _echo_error(f"Error: stage '{stage_name}' is not bound. Run: forest bind {stage_name} <PATH>")
+        ctx.exit(1)
+        raise AssertionError("unreachable")
+    return stage_cfg.path
+
+
+def _ensure_stages_bound(ctx: click.Context, config: ProjectConfig, stage_names: list[str]) -> bool:
+    return all(_ensure_stage_bound(ctx, stage_name, config.stages[stage_name]) for stage_name in stage_names)
+
+
+def _bound_stage_subset(ctx: click.Context, config: ProjectConfig) -> dict[str, StageConfig]:
+    """Return bound stages for bare push/pull, warning per unbound stage.
+
+    Exits when no stage is configured or none is bound.
+    """
+    if not config.stages:
+        _echo_error("Error: no stages configured. Run: forest add STAGE PATH or define stages in forest.yaml.")
+        ctx.exit(1)
+        return {}
+    bound = {name: cfg for name, cfg in config.stages.items() if cfg.path is not None}
+    for name in config.stages:
+        if name not in bound:
+            _echo_error(f"Warning: stage '{name}' is not bound; skipping. Run: forest bind {name} <PATH>")
+    if not bound:
+        _echo_error("Error: no stages are bound. Run: forest bind STAGE <PATH>")
+        ctx.exit(1)
+        return {}
+    return bound
+
+
+def _remote_use_hints(config: ProjectConfig) -> list[str]:
+    return [f"Run: forest remote use {name}" for name in sorted(config.remotes)]
+
+
+def _print_remote_use_hints(ctx: click.Context, config: ProjectConfig, *, err: bool = False) -> None:
+    echo = _echo_error if err else lambda message: _echo_info(ctx, message)
+    for hint in _remote_use_hints(config):
+        echo(hint)
+
+
+def _exit_stale_active_remote(ctx: click.Context, config: ProjectConfig, active_remote: str) -> None:
+    _echo_error(f"Error: active remote '{active_remote}' not found in config.")
+    _print_remote_use_hints(ctx, config, err=True)
+    ctx.exit(1)
+
+
+def _ensure_active_remote_known(ctx: click.Context, config: ProjectConfig, local_config: LocalConfig) -> None:
+    active_remote = local_config.active_remote
+    if active_remote is not None and active_remote not in config.remotes:
+        _exit_stale_active_remote(ctx, config, active_remote)
+
+
+def _resolve_remote(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    remote_name: str | None,
+) -> str | None:
+    """Resolve the target remote name.
+
+    Uses *remote_name* if given, otherwise falls back to the active remote
+    from ``.forest/local.yaml``.  On error, prints to stderr and exits.
+    """
+    if remote_name is not None:
+        if remote_name not in config.remotes:
+            _echo_error(f"Error: remote '{remote_name}' not found.")
+            ctx.exit(1)
+            return None  # unreachable
+        return remote_name
+
+    local_config = _load_active_local_config(ctx)
+    if local_config.active_remote is None:
+        if len(config.remotes) == 1:
+            return next(iter(config.remotes))
+        _echo_error("Error: no active remote set.")
+        if config.remotes:
+            _print_remote_use_hints(ctx, config, err=True)
+        else:
+            _echo_error("Run: forest remote add NAME URL")
+        ctx.exit(1)
+        return None  # unreachable
+
+    if local_config.active_remote not in config.remotes:
+        _exit_stale_active_remote(ctx, config, local_config.active_remote)
+        return None  # unreachable
+
+    return local_config.active_remote
+
+
+# ---------------------------------------------------------------------------
+# Init command
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.pass_context
+def init(ctx: click.Context) -> None:
+    """Initialize a forest workspace container.
+
+    Creates a nameless ``.forest/`` workspace registry only — no named
+    checkout and no root config. Names belong to
+    ``forest checkout create <name>``, which registers, activates, and
+    generates that checkout's ``forest.yaml``. Re-running ``init`` inside an
+    existing workspace reports setup status instead.
+    """
+    discovery_cwd = Path(ctx.obj["cwd"])
+    try:
+        workspace_root = find_workspace_root(discovery_cwd)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    if workspace_root is not None:
+        _init_workspace_setup(ctx, workspace_root)
+        return
+
+    # No workspace registry yet. Refuse to shadow a legacy root config.
+    legacy_config = discovery_cwd / "forest.yaml"
+    if legacy_config.exists():
+        _echo_error(
+            f"Error: legacy {legacy_config.name} found. "
+            "Run 'forest checkout adopt <name>' to migrate it into a workspace."
+        )
+        ctx.exit(1)
+        return
+
+    try:
+        save_workspace_config(discovery_cwd, WorkspaceConfig())
+        ensure_registry_gitignore(discovery_cwd)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    _echo_info(ctx, f"Initialized empty forest workspace in {discovery_cwd / '.forest'}")
+    _echo_info(ctx, "")
+    _echo_info(ctx, "Next steps:")
+    _echo_info(ctx, "  1. Run 'forest checkout create <name>' to create your first checkout")
+    _echo_info(ctx, "  2. Run 'forest remote add <name> <url>' to configure a remote")
+    _echo_info(ctx, "  3. Run 'forest bind <stage> <path>' once local data exists")
+
+
+def _init_workspace_setup(ctx: click.Context, workspace_root: Path) -> None:
+    """Run workspace setup checks instead of creating a legacy root config."""
+    gitignore_path = workspace_root / ".gitignore"
+    gitignore_text = gitignore_path.read_text() if gitignore_path.exists() else None
+    try:
+        registry = load_workspace_config(workspace_root)
+        checkout_name = read_head(workspace_root)
+        config, _data_root, _state_path = resolve_active_config(workspace_root)
+        ensure_workspace_gitignore(workspace_root, checkout_name)
+    except CheckoutError as exc:
+        if str(exc).startswith("No active checkout"):
+            names = sorted(registry.checkouts) if "registry" in locals() else []
+            _echo_info(ctx, "No active checkout selected.")
+            if names:
+                _echo_info(ctx, "Available checkouts:")
+                for name in names:
+                    _echo_info(ctx, f"  {name}")
+                    _echo_info(ctx, f"Run: forest checkout {name}")
+            else:
+                _echo_info(ctx, "Run: forest checkout NAME")
+            return
+        _restore_text(gitignore_path, gitignore_text)
+        _handle_checkout_error(ctx, exc)
+        return
+
+    _echo_info(ctx, f"Workspace checkout '{checkout_name}' is active.")
+    missing = [stage_name for stage_name, stage_cfg in config.stages.items() if stage_cfg.path is None]
+    for stage_name in missing:
+        _echo_info(ctx, f"Run: forest bind {stage_name} <PATH>")
+
+
+def _migrate_rename_layout(root: Path) -> list[str]:
+    """Rename legacy biostore metadata to forest names; return human-readable moves."""
+    moved: list[str] = []
+    old_meta = root / ".biostore"
+    if old_meta.exists():
+        new_meta = root / ".forest"
+        old_meta.rename(new_meta)
+        moved.append(".biostore/ -> .forest/")
+        checkouts = new_meta / "checkouts"
+        if checkouts.is_dir():
+            for cdir in sorted(checkouts.iterdir()):
+                old_checkout_cfg = cdir / "biostore.yaml"
+                if old_checkout_cfg.is_file():
+                    old_checkout_cfg.rename(cdir / "forest.yaml")
+                    moved.append(f"checkouts/{cdir.name}/biostore.yaml -> forest.yaml")
+    old_root_cfg = root / "biostore.yaml"
+    if old_root_cfg.exists():
+        old_root_cfg.rename(root / "forest.yaml")
+        moved.append("biostore.yaml -> forest.yaml")
+    moved.extend(_migrate_rewrite_gitignore(root))
+    return moved
+
+
+def _migrate_rewrite_gitignore(root: Path) -> list[str]:
+    gitignore_path = root / ".gitignore"
+    if not gitignore_path.exists():
+        return []
+    text = gitignore_path.read_text()
+    new_text = text.replace(".biostore", ".forest").replace("biostore.yaml", "forest.yaml")
+    if new_text == text:
+        return []
+    gitignore_path.write_text(new_text)
+    return [".gitignore patterns rewritten"]
+
+
+@main.command()
+@click.pass_context
+def migrate(ctx: click.Context) -> None:
+    """Migrate a legacy biostore layout in place to forest.
+
+    Renames ``.biostore/`` to ``.forest/`` and ``biostore.yaml`` to
+    ``forest.yaml`` (including each checkout's shared config), rewrites the
+    managed .gitignore patterns, and verifies the registry still parses.
+    Schema names are unchanged, so ``schema:`` references need no edits.
+    Refuses to run if a ``.forest/`` or ``forest.yaml`` already exists.
+    """
+    root = Path(ctx.obj["cwd"])
+    new_meta = root / ".forest"
+    new_root_cfg = root / "forest.yaml"
+
+    if not (root / ".biostore").exists() and not (root / "biostore.yaml").exists():
+        _echo_error("Error: no legacy biostore layout found (.biostore/ or biostore.yaml).")
+        ctx.exit(1)
+        return
+    if new_meta.exists() or new_root_cfg.exists():
+        _echo_error("Error: .forest/ or forest.yaml already exists; refusing to overwrite. Migrate manually.")
+        ctx.exit(1)
+        return
+
+    for line in _migrate_rename_layout(root):
+        _echo_info(ctx, f"  {line}")
+
+    try:
+        if (new_meta / "config.yaml").exists():
+            load_workspace_config(root)
+        elif new_root_cfg.exists():
+            load_config(new_root_cfg)
+    except (CheckoutError, ConfigError) as exc:
+        _echo_error(f"Error: migration moved files but the config did not parse: {exc}")
+        ctx.exit(1)
+        return
+
+    _echo_info(ctx, "")
+    _echo_info(ctx, "Migration complete.")
+
+
+class CheckoutGroup(click.Group):
+    """Checkout group that treats unknown subcommands as checkout names."""
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        command = super().get_command(ctx, cmd_name)
+        if command is not None or cmd_name.startswith("-"):
+            return command
+
+        @click.command(name=cmd_name)
+        @click.pass_context
+        def switch_command(switch_ctx: click.Context) -> None:
+            _checkout_switch(switch_ctx, cmd_name)
+
+        return switch_command
+
+
+def _require_checkout_workspace(ctx: click.Context) -> Path:
+    """Return workspace root or exit with checkout-workspace error."""
+    try:
+        workspace_root = find_workspace_root(Path(ctx.obj["cwd"]))
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        raise AssertionError("unreachable") from exc
+    if workspace_root is None:
+        _echo_error("Error: no checkout workspace found.")
+        ctx.exit(1)
+        raise AssertionError("unreachable")
+    return workspace_root
+
+
+def _require_binding_workspace_context(ctx: click.Context) -> ProjectContext:
+    """Return active workspace context for binding-only commands."""
+    _require_checkout_workspace(ctx)
+    project_context = _get_project_context(ctx)
+    if project_context.mode != "workspace":
+        _echo_error("Error: stage binding commands require a checkout workspace.")
+        ctx.exit(1)
+        raise AssertionError("unreachable")
+    return project_context
+
+
+def _resolve_cli_path(ctx: click.Context, path: str | Path) -> Path:
+    """Resolve a user path against the CLI discovery cwd."""
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = Path(ctx.obj["cwd"]) / candidate
+    return candidate.resolve(strict=False)
+
+
+def _display_path(path: Path) -> str:
+    return str(path) if path.is_absolute() else path.as_posix()
+
+
+def _restore_text(path: Path, text: str | None) -> None:
+    if text is None:
+        path.unlink(missing_ok=True)
+        return
+    atomic_write(path, text)
+
+
+def _stored_data_path(ctx: click.Context, path: str | Path, workspace_root: Path) -> tuple[Path, Path]:
+    """Resolve, safety-check, and normalize a local data path for local.yaml."""
+    resolved = _resolve_cli_path(ctx, path)
+    try:
+        safe_path = validate_workspace_data_path(resolved, workspace_root)
+    except CheckoutError as exc:
+        _echo_error(f"Error: {exc}")
+        ctx.exit(1)
+        raise AssertionError("unreachable") from exc
+    return safe_path, normalize_workspace_path(safe_path, workspace_root)
+
+
+def _registered_stage_names(config: ProjectConfig) -> str:
+    names = sorted(config.stages)
+    return ", ".join(names) if names else "(none)"
+
+
+def _bind_list(ctx: click.Context, config: ProjectConfig, local_config: LocalConfig) -> None:
+    """List shared stages and local bindings."""
+    if not config.stages:
+        _echo_info(ctx, "No stages configured.")
+        return
+    for stage_name in sorted(config.stages):
+        binding = local_config.stage_paths.get(stage_name)
+        marker = _display_path(binding) if binding is not None else "<unbound>"
+        _echo_info(ctx, f"{stage_name}\t{marker}")
+
+
+def _require_shared_stage(ctx: click.Context, config: ProjectConfig, stage_name: str) -> None:
+    if stage_name not in config.stages:
+        _echo_error(f"Error: stage '{stage_name}' not found; registered stages: {_registered_stage_names(config)}")
+        ctx.exit(1)
+
+
+def _checkout_create_root(ctx: click.Context, checkout_name: str) -> Path:
+    """Return root where checkout create may write, rejecting legacy/ambiguous state."""
+    start = Path(ctx.obj["cwd"])
+    try:
+        workspace_root = find_workspace_root(start)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        raise AssertionError("unreachable") from exc
+    if workspace_root is not None:
+        return workspace_root
+
+    root = find_project_boundary(start)
+    current = start
+    while True:
+        if (current / "forest.yaml").exists():
+            _echo_error(f"Error: legacy root config found: {current / 'forest.yaml'}")
+            _echo_error(f"Run: forest checkout adopt {checkout_name}")
+            ctx.exit(1)
+            raise AssertionError("unreachable")
+        if current == root or current.parent == current:
+            break
+        current = current.parent
+
+    if not (root / ".forest").exists() and not (root / ".git").exists():
+        current = root
+        while current.parent != current:
+            current = current.parent
+            if (current / "forest.yaml").exists():
+                _echo_error(f"Error: legacy root config found: {current / 'forest.yaml'}")
+                _echo_error(f"Run: forest checkout adopt {checkout_name}")
+                ctx.exit(1)
+                raise AssertionError("unreachable")
+    return root
+
+
+def _active_checkout_or_none(workspace_root: Path, names: list[str]) -> str | None:
+    head_path = workspace_root / ".forest" / "HEAD"
+    if not head_path.exists():
+        return None
+    active_name = read_head(workspace_root)
+    if active_name not in names:
+        raise CheckoutError(f"Active checkout '{active_name}' is not registered in workspace config.")
+    return active_name
+
+
+def _checkout_list(ctx: click.Context) -> None:
+    """List registered checkouts from registry and HEAD only."""
+    workspace_root = _require_checkout_workspace(ctx)
+    try:
+        names = list_checkouts(workspace_root)
+        active_name = _active_checkout_or_none(workspace_root, names)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    for name in names:
+        marker = "* " if name == active_name else "  "
+        _echo_info(ctx, f"{marker}{name}")
+
+    if active_name is None and names:
+        for name in names:
+            _echo_info(ctx, f"Run: forest checkout {name}")
+
+
+def _checkout_setup_guidance(ctx: click.Context, workspace_root: Path, checkout_name: str) -> None:
+    """Print next setup commands for a switched checkout without mutating local state."""
+    shared_path, local_path, _state_path = checkout_metadata_paths(workspace_root, checkout_name)
+    try:
+        config = load_config(shared_path)
+        local_config = load_local_config_file(local_path)
+    except ConfigError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    for stage_name, stage_cfg in config.stages.items():
+        if stage_cfg.path is None and stage_name not in local_config.stage_paths:
+            _echo_info(ctx, f"Run: forest bind {stage_name} <PATH>")
+
+    if not config.remotes:
+        _echo_info(ctx, "Run: forest remote add NAME URL")
+    elif local_config.active_remote is None and len(config.remotes) > 1:
+        for remote_name in sorted(config.remotes):
+            _echo_info(ctx, f"Run: forest remote use {remote_name}")
+
+
+def _checkout_create_flow(ctx: click.Context, checkout_name: str, *, message: str) -> Path | None:
+    """Create, register, and activate a checkout; return the workspace root."""
+    workspace_root = _checkout_create_root(ctx, checkout_name)
+    try:
+        create_checkout(workspace_root, checkout_name)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return None
+
+    _echo_info(ctx, message)
+    return workspace_root
+
+
+def _checkout_switch(ctx: click.Context, checkout_name: str) -> None:
+    """Switch HEAD to a checkout, creating it first when it is not registered."""
+    try:
+        workspace_root = find_workspace_root(Path(ctx.obj["cwd"]))
+        registered = workspace_root is not None and checkout_name in load_workspace_config(workspace_root).checkouts
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    if not registered:
+        created_root = _checkout_create_flow(
+            ctx,
+            checkout_name,
+            message=f"Created and switched to new checkout '{checkout_name}'.",
+        )
+        if created_root is not None:
+            _checkout_setup_guidance(ctx, created_root, checkout_name)
+        return
+
+    assert workspace_root is not None
+    try:
+        switch_checkout(workspace_root, checkout_name)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    _echo_info(ctx, f"Switched to checkout '{checkout_name}'.")
+    _checkout_setup_guidance(ctx, workspace_root, checkout_name)
+
+
+def _stdin_is_tty() -> bool:
+    """Return whether stdin is an interactive terminal."""
+    return sys.stdin.isatty()
+
+
+def _validate_checkout_remove_target(workspace_root: Path, checkout_name: str) -> None:
+    registry = require_registered_checkout(workspace_root, checkout_name)
+    head_path = workspace_root / ".forest" / "HEAD"
+    if head_path.exists():
+        active_name = read_head(workspace_root)
+        if active_name not in registry.checkouts:
+            raise CheckoutError(f"Active checkout '{active_name}' is not registered in workspace config.")
+
+
+@main.group(cls=CheckoutGroup, invoke_without_command=True)
+@click.pass_context
+def checkout(ctx: click.Context) -> None:
+    """Manage checkout workspaces."""
+    if ctx.invoked_subcommand is None:
+        _checkout_list(ctx)
+
+
+@checkout.command("list")
+@click.pass_context
+def checkout_list(ctx: click.Context) -> None:
+    """List registered checkouts."""
+    _checkout_list(ctx)
+
+
+@checkout.command("create")
+@click.argument("name")
+@click.pass_context
+def checkout_create(ctx: click.Context, name: str) -> None:
+    """Create and activate a checkout."""
+    _checkout_create_flow(ctx, name, message=f"Created checkout '{name}'.")
+
+
+@checkout.command("adopt")
+@click.argument("name")
+@click.pass_context
+def checkout_adopt(ctx: click.Context, name: str) -> None:
+    """Adopt a legacy root project into a checkout workspace."""
+    try:
+        adopt_checkout(Path(ctx.obj["cwd"]), name)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    _echo_info(ctx, f"Adopted legacy project as checkout '{name}'.")
+
+
+@checkout.command("current")
+@click.pass_context
+def checkout_current(ctx: click.Context) -> None:
+    """Print the active checkout name."""
+    workspace_root = _require_checkout_workspace(ctx)
+    try:
+        checkout_name = read_head(workspace_root)
+        registry = load_workspace_config(workspace_root)
+        if checkout_name not in registry.checkouts:
+            _echo_error(f"Error: active checkout '{checkout_name}' is not registered in workspace config.")
+            ctx.exit(1)
+            return
+        if not checkout_dir(workspace_root, checkout_name).is_dir():
+            _echo_error(f"Error: active checkout '{checkout_name}' metadata directory is missing.")
+            ctx.exit(1)
+            return
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    _echo_info(ctx, checkout_name)
+
+
+@checkout.command("remove")
+@click.argument("name")
+@click.option("--yes", is_flag=True, help="Skip the confirmation prompt (for scripted cleanup).")
+@click.pass_context
+def checkout_remove(ctx: click.Context, name: str, yes: bool) -> None:
+    """Remove checkout metadata after confirmation (or with --yes)."""
+    workspace_root = _require_checkout_workspace(ctx)
+    try:
+        _validate_checkout_remove_target(workspace_root, name)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    if not yes:
+        if not _stdin_is_tty():
+            _echo_error("Error: checkout remove requires an interactive terminal.")
+            ctx.exit(1)
+            return
+
+        if not click.confirm(f"Remove checkout '{name}' metadata?", default=False):
+            _echo_info(ctx, "Aborted.")
+            ctx.exit(1)
+            return
+
+    try:
+        removed_head = remove_checkout_metadata(workspace_root, name)
+    except CheckoutError as exc:
+        _handle_checkout_error(ctx, exc)
+        return
+
+    _echo_info(ctx, f"Removed checkout '{name}'.")
+    if removed_head:
+        _echo_info(ctx, "No active checkout selected.")
+
+
+@main.command("add")
+@click.argument("stage")
+@click.argument("path", type=click.Path(path_type=Path))
+@click.option(
+    "--sync-by",
+    "sync_by",
+    type=click.Choice(["subdirectory", "directory", "file"]),
+    default="subdirectory",
+    show_default=True,
+    help="Unit discovery mode for STAGE.",
+)
+@click.pass_context
+def add_stage(
+    ctx: click.Context, stage: str, path: Path, sync_by: Literal["directory", "subdirectory", "file"]
+) -> None:
+    """Register STAGE and bind it to local PATH in the active checkout."""
+    project_context = _require_binding_workspace_context(ctx)
+    assert project_context.checkout_name is not None
+    shared_config = _load_writable_project_config(ctx)
+    local_config = _load_active_local_config(ctx)
+
+    try:
+        validate_token(stage, kind="stage name", reserved_names=RESERVED_CHECKOUT_NAMES)
+    except CheckoutError as exc:
+        _echo_error(f"Error: {exc}")
+        ctx.exit(1)
+        return
+
+    if stage in shared_config.stages:
+        _echo_error(f"Error: stage '{stage}' already exists. Use 'forest bind {stage} PATH'.")
+        ctx.exit(1)
+        return
+
+    _resolved_path, stored_path = _stored_data_path(ctx, path, project_context.data_root)
+
+    stages = dict(shared_config.stages)
+    stages[stage] = StageConfig(remote_path=Path(project_context.checkout_name) / stage, sync_by=sync_by)
+    _save_project_config(ctx, shared_config.model_copy(update={"stages": stages}, deep=True))
+
+    stage_paths = dict(local_config.stage_paths)
+    stage_paths[stage] = stored_path
+    _save_active_local_config(ctx, local_config.model_copy(update={"stage_paths": stage_paths}, deep=True))
+
+    _echo_info(ctx, f"Added stage '{stage}' -> {_display_path(stored_path)}")
+
+
+@main.command("bind")
+@click.argument("stage", required=False)
+@click.argument("path", required=False, type=click.Path(path_type=Path))
+@click.pass_context
+def bind_stage(ctx: click.Context, stage: str | None, path: Path | None) -> None:
+    """List or update local stage path bindings for the active checkout."""
+    project_context = _require_binding_workspace_context(ctx)
+    shared_config = _load_writable_project_config(ctx)
+    local_config = _load_active_local_config(ctx)
+
+    if stage is None and path is None:
+        _bind_list(ctx, shared_config, local_config)
+        return
+    if stage is None or path is None:
+        raise click.UsageError("bind requires STAGE PATH, or no arguments to list bindings.")
+
+    _require_shared_stage(ctx, shared_config, stage)
+    _resolved_path, stored_path = _stored_data_path(ctx, path, project_context.data_root)
+    old_path = local_config.stage_paths.get(stage)
+
+    stage_paths = dict(local_config.stage_paths)
+    stage_paths[stage] = stored_path
+    _save_active_local_config(ctx, local_config.model_copy(update={"stage_paths": stage_paths}, deep=True))
+
+    if old_path is None:
+        _echo_info(ctx, f"Bound stage '{stage}' -> {_display_path(stored_path)}")
+    else:
+        _echo_info(ctx, f"Bound stage '{stage}': {_display_path(old_path)} -> {_display_path(stored_path)}")
+
+
+@main.command("unbind")
+@click.argument("stage")
+@click.pass_context
+def unbind_stage(ctx: click.Context, stage: str) -> None:
+    """Remove a local stage path binding from the active checkout."""
+    _require_binding_workspace_context(ctx)
+    shared_config = _load_writable_project_config(ctx)
+    local_config = _load_active_local_config(ctx)
+    _require_shared_stage(ctx, shared_config, stage)
+
+    old_path = local_config.stage_paths.get(stage)
+    if old_path is None:
+        _echo_info(ctx, f"Stage '{stage}' already unbound.")
+        return
+
+    stage_paths = dict(local_config.stage_paths)
+    del stage_paths[stage]
+    _save_active_local_config(ctx, local_config.model_copy(update={"stage_paths": stage_paths}, deep=True))
+    _echo_info(ctx, f"Unbound stage '{stage}' from {_display_path(old_path)}.")
+
+
+@main.group()
+def remote() -> None:
+    """Manage remote storage endpoints."""
+
+
+def _validate_remote_add_inputs(
+    ctx: click.Context,
+    name: str,
+    url: str,
+    endpoint: str | None,
+    config: ProjectConfig,
+) -> None:
+    try:
+        validate_token(
+            name,
+            kind="remote name",
+            reserved_names=RESERVED_REMOTE_NAMES,
+            existing_names=set(config.remotes),
+        )
+    except CheckoutError as exc:
+        _echo_error(f"Error: {exc}")
+        ctx.exit(1)
+
+    if remote_url_has_secret_material(url):
+        _echo_error("Error: remote URL contains embedded credentials or token-like material.")
+        _echo_error("Use --profile for S3 auth, or --key-file and --known-hosts for SFTP auth.")
+        ctx.exit(1)
+    if endpoint is not None and remote_url_has_secret_material(endpoint):
+        _echo_error("Error: remote endpoint contains embedded credentials or token-like material.")
+        ctx.exit(1)
+
+
+@remote.command("add")
+@click.argument("name")
+@click.argument("url")
+@click.option("--region", default=None, help="S3 region (e.g. us-east-2).")
+@click.option("--endpoint", default=None, help="S3-compatible endpoint URL (non-AWS S3).")
+@click.option("--profile", default=None, help="S3 auth profile name (e.g. scripps).")
+@click.option("--key-file", "key_file", default=None, help="SFTP private key file path.")
+@click.option("--known-hosts", "known_hosts", default=None, help="SFTP known_hosts file path.")
+@click.pass_context
+def remote_add(
+    ctx: click.Context,
+    name: str,
+    url: str,
+    region: str | None,
+    endpoint: str | None,
+    profile: str | None,
+    key_file: str | None,
+    known_hosts: str | None,
+) -> None:
+    """Add a named remote (NAME) with the given URL."""
+    project_context = _get_project_context(ctx)
+    config = _load_writable_project_config(ctx)
+    _validate_remote_add_inputs(ctx, name, url, endpoint, config)
+    local_config = _load_active_local_config(ctx)
+    _ensure_active_remote_known(ctx, config, local_config)
+
+    is_first = not config.remotes
+
+    config.remotes[name] = RemoteConfig(
+        url=url,
+        region=region,
+        endpoint=endpoint,
+        profile=profile,
+        key_file=key_file,
+        known_hosts=known_hosts,
+    )
+    _save_project_config(ctx, config)
+
+    if project_context.mode == "legacy" and is_first:
+        local_config.active_remote = name
+        _save_active_local_config(ctx, local_config)
+
+    _echo_info(ctx, f"Added remote '{name}' -> {url}")
+    if project_context.mode == "legacy" and is_first:
+        _echo_info(ctx, f"Set '{name}' as active remote.")
+
+
+@remote.command("remove")
+@click.argument("name")
+@click.pass_context
+def remote_remove(ctx: click.Context, name: str) -> None:
+    """Remove a named remote."""
+    config = _load_writable_project_config(ctx)
+
+    if name not in config.remotes:
+        _echo_error(f"Error: remote '{name}' not found.")
+        ctx.exit(1)
+        return
+
+    local_config = _load_active_local_config(ctx)
+    _ensure_active_remote_known(ctx, config, local_config)
+    was_active = local_config.active_remote == name
+
+    del config.remotes[name]
+    _save_project_config(ctx, config)
+    if was_active:
+        local_config.active_remote = None
+        _save_active_local_config(ctx, local_config)
+    _echo_info(ctx, f"Removed remote '{name}'.")
+    if was_active:
+        _print_remote_use_hints(ctx, config)
+
+
+@remote.command("list")
+@click.pass_context
+def remote_list(ctx: click.Context) -> None:
+    """List all configured remotes."""
+    config = _load_project_config(ctx)
+
+    if not config.remotes:
+        _echo_info(ctx, "No remotes configured. Use 'forest remote add' to add one.")
+        return
+
+    local_config = _load_active_local_config(ctx)
+    active = local_config.active_remote
+    if active is not None and active not in config.remotes:
+        _exit_stale_active_remote(ctx, config, active)
+        return
+
+    for name, remote_cfg in sorted(config.remotes.items()):
+        marker = "* " if name == active else "  "
+        _echo_info(ctx, f"{marker}{name}\t{remote_cfg.url}\t[{remote_cfg.remote_type}]")
+
+    if active is None:
+        _print_remote_use_hints(ctx, config)
+
+
+@remote.command("use")
+@click.argument("name")
+@click.pass_context
+def remote_use(ctx: click.Context, name: str) -> None:
+    """Set the active remote by name."""
+    config = _load_project_config(ctx)
+
+    if name not in config.remotes:
+        _echo_error(f"Error: remote '{name}' not found.")
+        ctx.exit(1)
+        return
+
+    local_config = _load_active_local_config(ctx)
+    local_config.active_remote = name
+    _save_active_local_config(ctx, local_config)
+    _echo_info(ctx, f"Active remote set to '{name}'.")
+
+
+@remote.command("show")
+@click.argument("name")
+@click.pass_context
+def remote_show(ctx: click.Context, name: str) -> None:
+    """Show details of a named remote."""
+    config = _load_project_config(ctx)
+
+    if name not in config.remotes:
+        _echo_error(f"Error: remote '{name}' not found.")
+        ctx.exit(1)
+        return
+
+    remote_cfg = config.remotes[name]
+    _echo_info(ctx, f"Name:      {name}")
+    _echo_info(ctx, f"URL:       {remote_cfg.url}")
+    _echo_info(ctx, f"Type:      {remote_cfg.remote_type}")
+    if remote_cfg.region:
+        _echo_info(ctx, f"Region:    {remote_cfg.region}")
+    if remote_cfg.endpoint:
+        _echo_info(ctx, f"Endpoint:  {remote_cfg.endpoint}")
+    if remote_cfg.profile:
+        _echo_info(ctx, f"Profile:   {remote_cfg.profile}")
+    if remote_cfg.key_file:
+        _echo_info(ctx, f"Key file:  {remote_cfg.key_file}")
+    if remote_cfg.known_hosts:
+        _echo_info(ctx, f"Known hosts: {remote_cfg.known_hosts}")
+
+
+def _observed_transfer(op: str, label: str, remote_name: str, fn: Callable[[], TransferResult]) -> TransferResult:
+    """Run one unit transfer with timing metrics and structured result logs."""
+    tags = {"unit": label, "remote": remote_name}
+    with metrics.timed(f"{op}.duration_seconds", tags=tags):
+        xfer = fn()
+    if xfer.errors:
+        _log.error(f"{op} unit failed", extra={"unit": label, "remote": remote_name, "errors": len(xfer.errors)})
+    else:
+        metrics.record_transfer(op, files=xfer.files_transferred, transferred_bytes=xfer.bytes_transferred, tags=tags)
+        _log.info(
+            f"{op} unit ok",
+            extra={
+                "unit": label,
+                "remote": remote_name,
+                "files": xfer.files_transferred,
+                "bytes": xfer.bytes_transferred,
+            },
+        )
+    return xfer
+
+
+def _format_size(total_bytes: int) -> str:
+    """Format byte count as human-readable size string."""
+    if total_bytes >= 1024 * 1024 * 1024:
+        return f"{total_bytes / (1024**3):.1f} GB"
+    if total_bytes >= 1024 * 1024:
+        return f"{total_bytes / (1024**2):.1f} MB"
+    if total_bytes >= 1024:
+        return f"{total_bytes / 1024:.1f} KB"
+    return f"{total_bytes} B"
+
+
+def _resolve_unit_path(
+    stage_cfg: StageConfig,
+    project_root: Path,
+    unit_id: str,
+) -> Path:
+    """Resolve the absolute path for a unit respecting sync_by mode."""
+    if stage_cfg.path is None:
+        raise ValueError("Stage path is not configured. Bind the stage before using local files.")
+    stage_path = stage_cfg.path
+    if stage_cfg.sync_by == "directory":
+        return project_root / stage_path
+    return project_root / stage_path / unit_id
+
+
+def _remote_prefix_for_unit(stage_cfg: StageConfig, uid: str) -> str:
+    """Compute the remote prefix string for a data unit.
+
+    Uses ``remote_path`` when set on the stage; otherwise falls back to
+    the stage ``path``.
+    """
+    remote_base = _effective_remote_base(stage_cfg)
+    unit_prefix = remote_base if stage_cfg.sync_by == "directory" else remote_base / uid
+    return PurePosixPath(unit_prefix).as_posix()
+
+
+def _entry_remote_path_matches_current(
+    config: ProjectConfig,
+    stage_cfg: StageConfig,
+    uid: str,
+    entry: SyncEntry,
+) -> bool:
+    if entry.remote_path is None:
+        return True
+    remote_cfg = config.remotes.get(entry.remote)
+    if remote_cfg is None:
+        return True
+    current_remote_path = remote_cfg.url.rstrip("/") + "/" + _remote_prefix_for_unit(stage_cfg, uid)
+    return entry.remote_path == current_remote_path
+
+
+def _remote_key_for_file(
+    file_path: Path,
+    stage_cfg: StageConfig,
+    project_root: Path,
+) -> str:
+    """Compute the remote key for a local file within a stage.
+
+    When ``remote_path`` is set on the stage, the key is built by taking
+    the file relative to the stage's absolute directory and prepending
+    the ``remote_path``.  Otherwise, uses the file relative to the
+    project root (existing behaviour).
+    """
+    if stage_cfg.remote_path is not None:
+        if stage_cfg.path is None:
+            raise ValueError("Stage path is not configured. Bind the stage before using local files.")
+        stage_abs = (project_root / stage_cfg.path).resolve()
+        file_rel = file_path.resolve().relative_to(stage_abs)
+        return (PurePosixPath(str(stage_cfg.remote_path)) / file_rel.as_posix()).as_posix()
+    return file_path.relative_to(project_root).as_posix()
+
+
+def _validate_stage_option(ctx: click.Context, config: ProjectConfig, stage: str | None) -> None:
+    """Exit when --stage names an unknown stage."""
+    if stage and stage not in config.stages:
+        _echo_error(f"Error: stage '{stage}' not found in config.")
+        ctx.exit(1)
+
+
+def _resolve_manifest_pairs_or_exit(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    id_value: str,
+    stage: str | None,
+    *,
+    require_stage_column: bool = False,
+) -> list[tuple[str, str]]:
+    """Resolve --id to (stage, unit_id) pairs, exiting with a message on failure."""
+    if config.manifest is None:
+        _echo_error("Error: --id requires a manifest section in forest.yaml.")
+        ctx.exit(1)
+        return []
+    manifest_path = project_root / config.manifest.file
+    try:
+        manifest = load_manifest(manifest_path)
+    except FileNotFoundError:
+        _echo_error(f"Error: Manifest file not found: {manifest_path}")
+        ctx.exit(1)
+        return []
+    if require_stage_column and stage and stage not in config.manifest.stage_columns:
+        _echo_error(
+            f"Error: stage '{stage}' is not in manifest.stage_columns. "
+            f"Available stages: {list(config.manifest.stage_columns.keys())}"
+        )
+        ctx.exit(1)
+        return []
+    try:
+        return resolve_manifest_pairs(config, manifest, id_value, stage)
+    except ManifestError as exc:
+        _echo_error(f"Error: {exc}")
+        ctx.exit(1)
+        return []
+
+
+def _validate_targets_all(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    stage: str | None,
+) -> list[tuple[str, str, Path]]:
+    stages = {stage: config.stages[stage]} if stage else config.stages
+    if not _ensure_stages_bound(ctx, config, list(stages)):
+        return []
+    targets: list[tuple[str, str, Path]] = []
+    for stage_name, stage_cfg in stages.items():
+        for uid, abs_path in discover_units(stage_cfg, project_root):
+            targets.append((stage_name, uid, abs_path))
+    return targets
+
+
+def _validate_targets_by_id(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    id_value: str,
+    stage: str | None,
+) -> list[tuple[str, str, Path]]:
+    pairs = _resolve_manifest_pairs_or_exit(ctx, config, project_root, id_value, stage, require_stage_column=True)
+    if not _ensure_stages_bound(ctx, config, sorted({stage_name for stage_name, _uid in pairs})):
+        return []
+    targets: list[tuple[str, str, Path]] = []
+    for stage_name, uid in pairs:
+        stage_cfg = config.stages[stage_name]
+        abs_path = _resolve_unit_path(stage_cfg, project_root, uid)
+        targets.append((stage_name, uid, abs_path))
+    if not targets:
+        assert config.manifest is not None
+        _echo_error(f"Error: ID '{id_value}' not found in manifest column '{config.manifest.id_column}'.")
+        ctx.exit(1)
+        return []
+    return targets
+
+
+def _validate_targets_explicit(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    unit_ids: tuple[str, ...],
+    stage: str | None,
+) -> list[tuple[str, str, Path]]:
+    if not stage:
+        _echo_error("Error: --stage is required when specifying unit IDs.")
+        ctx.exit(1)
+        return []
+    if stage not in config.stages:
+        _echo_error(f"Error: stage '{stage}' not found in config.")
+        ctx.exit(1)
+        return []
+    stage_cfg = config.stages[stage]
+    if not _ensure_stage_bound(ctx, stage, stage_cfg):
+        return []
+    return [(stage, uid, _resolve_unit_path(stage_cfg, project_root, uid)) for uid in unit_ids]
+
+
+def _resolve_validate_targets(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    unit_ids: tuple[str, ...],
+    stage: str | None,
+    id_value: str | None,
+    all_flag: bool,
+) -> list[tuple[str, str, Path]]:
+    """Resolve validate targets to (stage_name, unit_id, unit_abs_path) triples.
+
+    Returns an empty list and exits with error on problems.
+    """
+    if all_flag:
+        return _validate_targets_all(ctx, config, project_root, stage)
+    if id_value:
+        return _validate_targets_by_id(ctx, config, project_root, id_value, stage)
+    if unit_ids:
+        return _validate_targets_explicit(ctx, config, project_root, unit_ids, stage)
+    _echo_error("Error: provide UNIT_IDs with --stage, use --id, or use --all.")
+    ctx.exit(1)
+    return []
+
+
+@dataclass
+class _TransferRequest:
+    """Resolved per-command context shared by unit transfer helpers."""
+
+    transport: RcloneTransport
+    remote_name: str
+    remote_cfg: RemoteConfig
+    config: ProjectConfig
+    project_root: Path
+    state_path: Path
+    dry_run: bool
+    exclude: tuple[str, ...] = ()
+
+
+def _excluded_paths(abs_path: Path, exclude: tuple[str, ...]) -> set[Path]:
+    """Expand ad-hoc --exclude globs to the set of files they cover."""
+    excluded: set[Path] = set()
+    for pattern in exclude:
+        for match in abs_path.glob(pattern):
+            if match.is_file():
+                excluded.add(match)
+            elif match.is_dir():
+                for f in match.rglob("*"):
+                    if f.is_file():
+                        excluded.add(f)
+    return excluded
+
+
+def _strip_forest_paths(sync_files: list[Path], project_root: Path) -> list[Path]:
+    """Drop files that live under any .forest/ metadata directory."""
+    kept: list[Path] = []
+    for f in sync_files:
+        try:
+            parts = f.relative_to(project_root).parts
+        except ValueError:
+            parts = f.parts
+        if ".forest" not in parts:
+            kept.append(f)
+    return kept
+
+
+def _unit_sync_files(abs_path: Path, project_root: Path, exclude: tuple[str, ...]) -> list[Path]:
+    """Collect a unit's pushable files; OS junk, --exclude matches, and .forest/ are dropped."""
+    sync_files = [abs_path] if abs_path.is_file() else list_sync_files(abs_path)
+    if exclude:
+        excluded_set = _excluded_paths(abs_path, exclude)
+        sync_files = [f for f in sync_files if f not in excluded_set]
+    return _strip_forest_paths(sync_files, project_root)
+
+
+def _last_synced_entry(state_path: Path, remote_name: str, stage_name: str, uid: str) -> SyncEntry | None:
+    """Return the newest sync entry for (remote, stage, unit) from the locked state file."""
+    with checkout_lock(state_path):
+        current_state = load_state(state_path)
+    for entry in reversed(current_state.entries):
+        if entry.remote == remote_name and entry.stage == stage_name and entry.unit_id == uid:
+            return entry
+    return None
+
+
+def _matches_existing_push(existing: SyncEntry | None, checksum: str, remote_path: str) -> bool:
+    return existing is not None and existing.checksum == checksum and existing.remote_path == remote_path
+
+
+def _sync_entry_payload(
+    request: _TransferRequest,
+    stage_name: str,
+    uid: str,
+    stage_cfg: StageConfig,
+    local_path: Path,
+    remote_path: str,
+    checksum: str,
+    xfer: TransferResult,
+) -> dict[str, object]:
+    return {
+        "remote": request.remote_name,
+        "stage": stage_name,
+        "unit_id": uid,
+        "schema": stage_cfg.schema_,
+        "local_path": str(local_path),
+        "remote_path": remote_path,
+        "file_count": xfer.files_transferred,
+        "total_bytes": xfer.bytes_transferred,
+        "checksum": checksum,
+    }
+
+
+def _record_transfer(request: _TransferRequest, direction: Literal["push", "pull"], payload: dict[str, object]) -> None:
+    record = record_push if direction == "push" else record_pull
+    with checkout_lock(request.state_path):
+        save_state(record(load_state(request.state_path), payload), request.state_path)
+
+
+def _echo_push_file_details(ctx: click.Context, file_tuples: list[tuple[Path, str]]) -> None:
+    for f, remote_key in file_tuples:
+        _echo_verbose(ctx, f"  {remote_key} ({_format_size(f.stat().st_size)})")
+
+
+def _push_unit(ctx: click.Context, request: _TransferRequest, stage_name: str, uid: str, abs_path: Path) -> bool:
+    """Push one unit via transport; return False when the unit failed."""
+    stage_cfg = request.config.stages[stage_name]
+    stage_path = _required_stage_path(ctx, stage_name, stage_cfg)
+    label = f"{stage_name}/{uid}"
+
+    # Reject nonexistent explicit targets
+    if not abs_path.exists():
+        _echo_error(f"FAIL {label}  target path does not exist: {abs_path}")
+        return False
+
+    sync_files = _unit_sync_files(abs_path, request.project_root, request.exclude)
+
+    # Nothing left to transfer (filters removed everything): report a graceful
+    # no-op instead of a misleading "PUSH ... 0 files" and never invoke rclone
+    # on an empty list or record a transferred-bytes entry.
+    if not sync_files:
+        _echo_info(ctx, f"SKIP {label}  nothing to push")
+        return True
+
+    # For file mode, use stage dir as checksum base; otherwise use unit path
+    checksum_base = request.project_root / stage_path if stage_cfg.sync_by == "file" else abs_path
+    checksum = compute_checksum(checksum_base, sync_files)
+    current_remote_path = request.remote_cfg.url.rstrip("/") + "/" + _remote_prefix_for_unit(stage_cfg, uid)
+
+    # Skip when already synced under the active remote.
+    existing = _last_synced_entry(request.state_path, request.remote_name, stage_name, uid)
+    if _matches_existing_push(existing, checksum, current_remote_path):
+        _echo_info(ctx, f"SKIP {label}  already synced to {request.remote_name}")
+        return True
+
+    file_tuples = [(f, _remote_key_for_file(f, stage_cfg, request.project_root)) for f in sync_files]
+    size_str = _format_size(sum(f.stat().st_size for f in sync_files))
+
+    if request.dry_run:
+        _echo_info(ctx, f"PLAN {label}  {len(sync_files)} files, {size_str} -> {request.remote_name}")
+        _echo_push_file_details(ctx, file_tuples)
+        return True
+
+    # Push via transport (rclone streams --stats to stderr unless --quiet)
+    xfer = _observed_transfer(
+        "push",
+        label,
+        request.remote_name,
+        partial(request.transport.push, file_tuples, request.remote_cfg.url, quiet=ctx.obj.get("quiet", False)),
+    )
+    if _echo_transfer_errors(label, xfer):
+        return False
+
+    payload = _sync_entry_payload(request, stage_name, uid, stage_cfg, abs_path, current_remote_path, checksum, xfer)
+    # File snapshot enables detailed diff support.
+    payload["file_snapshot"] = {str(f.relative_to(checksum_base)): f.stat().st_size for f in sync_files}
+    _record_transfer(request, "push", payload)
+
+    _echo_info(ctx, f"PUSH {label}  {xfer.files_transferred} files, {size_str} -> {request.remote_name}")
+    _echo_push_file_details(ctx, file_tuples)
+    return True
+
+
+def _discover_bare_push_targets(
+    ctx: click.Context, config: ProjectConfig, project_root: Path
+) -> list[tuple[str, str, Path]]:
+    """Discover units across bound stages for bare push; report when nothing is found."""
+    bound_stages = _bound_stage_subset(ctx, config)
+    targets: list[tuple[str, str, Path]] = []
+    for stage_name, stage_cfg in bound_stages.items():
+        for uid, abs_path in discover_units(stage_cfg, project_root):
+            targets.append((stage_name, uid, abs_path))
+    if not targets:
+        _echo_info(ctx, "No units found in bound stages.")
+        _echo_sync_by_hints(ctx, project_root, bound_stages)
+    return targets
+
+
+def _echo_sync_by_hints(ctx: click.Context, project_root: Path, bound_stages: dict[str, StageConfig]) -> None:
+    for stage_name, stage_cfg in bound_stages.items():
+        stage_dir = project_root / stage_cfg.path if stage_cfg.path is not None else None
+        if stage_dir is not None and stage_dir.is_dir() and any(stage_dir.iterdir()):
+            _echo_info(
+                ctx,
+                f"Hint: stage '{stage_name}' has files but no {stage_cfg.sync_by} units; "
+                "check its sync_by mode in forest.yaml.",
+            )
+
+
+def _resolve_push_targets_before_remote(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    unit_ids: tuple[str, ...],
+    stage: str | None,
+    id_value: str | None,
+    all_flag: bool,
+) -> list[tuple[str, str, Path]] | None:
+    """Resolve push targets that are known before the remote resolves.
+
+    With --all only stage configuration and bindings are validated here; unit
+    discovery happens after the remote resolves (preserving historical output
+    order), signalled by returning None. Returns [] when there is nothing to
+    do and the situation was already reported.
+    """
+    if all_flag:
+        if not config.stages:
+            _echo_error("Error: no stages configured. Run: forest add STAGE PATH or define stages in forest.yaml.")
+            ctx.exit(1)
+        stages = {stage: config.stages[stage]} if stage else config.stages
+        _ensure_stages_bound(ctx, config, list(stages))
+        return None
+    if unit_ids or stage or id_value:
+        return _resolve_validate_targets(ctx, config, project_root, unit_ids, stage, id_value, False)
+    return _discover_bare_push_targets(ctx, config, project_root)
+
+
+def _acquire_transport(ctx: click.Context, remote_name: str, remote_cfg: RemoteConfig) -> RcloneTransport:
+    """Gate on rclone availability, build the transport backend, and echo the remote banner."""
+    # rclone is required for every transport operation (G3 baseline gating).
+    if not is_available():
+        _echo_error(f"Error: {RCLONE_INSTALL_MSG}")
+        ctx.exit(1)
+    try:
+        transport = get_transport(remote_cfg)
+    except ValueError as exc:
+        _echo_error(f"Error: {exc}")
+        ctx.exit(1)
+        raise AssertionError("unreachable") from exc
+    _preflight_remote_config(ctx, remote_cfg)
+    _echo_verbose(ctx, f"Using remote '{remote_name}' [{remote_cfg.remote_type}] at {remote_cfg.url}")
+    if remote_cfg.remote_type == "s3":
+        _echo_verbose(ctx, f"  backend={transport.backend_name}")
+    return transport
+
+
+@main.command()
+@click.argument("unit_ids", nargs=-1)
+@click.option("--stage", default=None, help="Stage to push from.")
+@click.option("--id", "id_value", default=None, help="Resolve units via manifest ID.")
+@click.option("--all", "all_flag", is_flag=True, help="Push all units in all stages.")
+@click.option("--force", "_force", is_flag=True, help="Retained for compatibility; no effect.")
+@click.option("--dry-run", is_flag=True, help="Show plan without transferring.")
+@click.option("--exclude", multiple=True, help="Ad-hoc exclude glob patterns.")
+@click.pass_context
+def push(
+    ctx: click.Context,
+    unit_ids: tuple[str, ...],
+    stage: str | None,
+    id_value: str | None,
+    all_flag: bool,
+    _force: bool,
+    dry_run: bool,
+    exclude: tuple[str, ...],
+) -> None:
+    """Push data units to a remote.
+
+    Resolves targets, transfers all files in each unit (minus OS junk and
+    ad-hoc --exclude matches) via transport, and records sync state on success.
+    """
+    config = _load_project_config(ctx)
+    project_root = _project_root(ctx)
+    _validate_stage_option(ctx, config, stage)
+
+    targets = _resolve_push_targets_before_remote(ctx, config, project_root, unit_ids, stage, id_value, all_flag)
+    if targets is not None and not targets:
+        return
+
+    remote_name = _resolve_remote(ctx, config, project_root, None)
+    if remote_name is None:
+        return  # unreachable — _resolve_remote exits on error
+    remote_cfg = config.remotes[remote_name]
+
+    # Resolve --all targets after the remote (reuse validate logic)
+    if all_flag:
+        targets = _resolve_validate_targets(ctx, config, project_root, unit_ids, stage, id_value, all_flag)
+        if not targets:
+            return
+    assert targets is not None
+
+    transport = _acquire_transport(ctx, remote_name, remote_cfg)
+    request = _TransferRequest(
+        transport=transport,
+        remote_name=remote_name,
+        remote_cfg=remote_cfg,
+        config=config,
+        project_root=project_root,
+        state_path=_state_path(ctx),
+        dry_run=dry_run,
+        exclude=exclude,
+    )
+
+    had_failure = False
+    for stage_name, uid, abs_path in targets:
+        if not _push_unit(ctx, request, stage_name, uid, abs_path):
+            had_failure = True
+
+    if had_failure:
+        monitoring.report_failure("push completed with errors", f"remote '{remote_name}'", command="push")
+        ctx.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Pull helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_metadata_remote_key(key: str) -> bool:
+    """Return True for forest/macOS metadata keys hidden from data views."""
+    parts = [part for part in key.split("/") if part]
+    return any(part == ".forest" or part == ".DS_Store" or part.startswith("._") for part in parts)
+
+
+def _safe_remote_file_key(key: str) -> PurePosixPath:
+    rel = PurePosixPath(key)
+    if key == "" or rel.is_absolute() or any(part in {"", ".", ".."} for part in rel.parts):
+        raise ValueError(f"unsafe remote key: {key}")
+    return rel
+
+
+def _non_metadata_remote_files(remote_files: list[RemoteFile]) -> list[RemoteFile]:
+    """Drop metadata keys before ls/status/pull grouping decisions."""
+    return [rf for rf in remote_files if not _is_metadata_remote_key(rf.key)]
+
+
+def _listed_remote_files(transport_obj: RcloneTransport, remote_url: str, prefix: str = "") -> list[RemoteFile]:
+    """List remote files and centralize metadata filtering."""
+    return _non_metadata_remote_files(transport_obj.ls(remote_url, prefix=prefix))
+
+
+def _subdirectory_remote_targets(
+    project_root: Path, stage_name: str, stage_path: Path, remote_files: list[RemoteFile]
+) -> list[tuple[str, str, Path]]:
+    unit_ids: set[str] = set()
+    for rf in remote_files:
+        parts = rf.key.split("/")
+        if parts:
+            unit_ids.add(parts[0])
+    return [(stage_name, uid, project_root / stage_path / uid) for uid in sorted(unit_ids)]
+
+
+def _file_remote_targets(
+    project_root: Path, stage_name: str, stage_path: Path, remote_files: list[RemoteFile]
+) -> list[tuple[str, str, Path]]:
+    targets: list[tuple[str, str, Path]] = []
+    seen: set[str] = set()
+    for rf in remote_files:
+        parts = rf.key.split("/")
+        if len(parts) == 1 and parts[0] not in seen:
+            seen.add(parts[0])
+            targets.append((stage_name, parts[0], project_root / stage_path / parts[0]))
+    return targets
+
+
+def _stage_remote_targets(
+    project_root: Path, stage_name: str, stage_cfg: StageConfig, stage_path: Path, remote_files: list[RemoteFile]
+) -> list[tuple[str, str, Path]]:
+    """Group a stage's remote listing into (stage, unit_id, local_path) targets."""
+    if stage_cfg.sync_by == "directory":
+        if remote_files:
+            return [(stage_name, stage_path.name, project_root / stage_path)]
+        return []
+    if stage_cfg.sync_by == "subdirectory":
+        return _subdirectory_remote_targets(project_root, stage_name, stage_path, remote_files)
+    if stage_cfg.sync_by == "file":
+        return _file_remote_targets(project_root, stage_name, stage_path, remote_files)
+    return []
+
+
+def _resolve_pull_all_targets(
+    ctx: click.Context,
+    project_root: Path,
+    transport_obj: RcloneTransport,
+    remote_url: str,
+    stages: dict[str, StageConfig],
+) -> list[tuple[str, str, Path]]:
+    """Discover units on the remote for the given stages (pull --all / bare pull)."""
+    targets: list[tuple[str, str, Path]] = []
+    for stage_name, stage_cfg in stages.items():
+        stage_path = _required_stage_path(ctx, stage_name, stage_cfg)
+        prefix = _effective_remote_base(stage_cfg).as_posix()
+        remote_files = _listed_remote_files(transport_obj, remote_url, prefix=prefix)
+        targets.extend(_stage_remote_targets(project_root, stage_name, stage_cfg, stage_path, remote_files))
+    return targets
+
+
+# ---------------------------------------------------------------------------
+# Pull command
+# ---------------------------------------------------------------------------
+
+
+def _resolve_pull_scope(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    unit_ids: tuple[str, ...],
+    stage: str | None,
+    id_value: str | None,
+    all_flag: bool,
+) -> tuple[list[tuple[str, str, Path]] | None, dict[str, StageConfig] | None]:
+    """Split pull arguments into explicit targets or stages to discover remotely.
+
+    Returns ``(targets, None)`` for explicit selection and ``(None, stages)``
+    when units must be discovered on the remote (bare pull / --all).
+    """
+    if not unit_ids and not stage and not id_value and not all_flag:
+        return None, _bound_stage_subset(ctx, config)
+    if all_flag:
+        if not config.stages:
+            _echo_error("Error: no stages configured. Run: forest add STAGE PATH or define stages in forest.yaml.")
+            ctx.exit(1)
+        pull_stages = {stage: config.stages[stage]} if stage else dict(config.stages)
+        _ensure_stages_bound(ctx, config, list(pull_stages))
+        return None, pull_stages
+    return _resolve_validate_targets(ctx, config, project_root, unit_ids, stage, id_value, False), None
+
+
+def _list_pull_all_targets(
+    ctx: click.Context,
+    request: _TransferRequest,
+    pull_stages: dict[str, StageConfig],
+) -> list[tuple[str, str, Path]]:
+    """Discover remote units for bare pull / --all; report when none exist."""
+    try:
+        targets = _resolve_pull_all_targets(
+            ctx, request.project_root, request.transport, request.remote_cfg.url, pull_stages
+        )
+    except RcloneError as exc:
+        _echo_error(f"Error: failed to list remote '{request.remote_name}': {_transport_error_detail(exc)}")
+        ctx.exit(1)
+        return []
+    if not targets:
+        _echo_info(ctx, "No units found on remote.")
+    return targets
+
+
+def _echo_pull_file_details(ctx: click.Context, remote_files: list[RemoteFile]) -> None:
+    for rf in remote_files:
+        _echo_verbose(ctx, f"  {rf.key} ({_format_size(rf.size)})")
+
+
+def _echo_transfer_errors(label: str, xfer: TransferResult) -> bool:
+    """Echo per-unit transport errors; return True when any occurred."""
+    for err in xfer.errors:
+        _echo_error(f"ERROR {label}  {err}")
+    return bool(xfer.errors)
+
+
+def _observed_pull(
+    ctx: click.Context, request: _TransferRequest, label: str, pull_tuples: list[tuple[str, Path]]
+) -> TransferResult:
+    # rclone streams --stats to stderr unless --quiet
+    return _observed_transfer(
+        "pull",
+        label,
+        request.remote_name,
+        partial(request.transport.pull, pull_tuples, request.remote_cfg.url, quiet=ctx.obj.get("quiet", False)),
+    )
+
+
+def _pull_file_unit(ctx: click.Context, request: _TransferRequest, stage_name: str, uid: str) -> bool:
+    """Pull a sync_by=file unit as a direct file transfer; return False on failure."""
+    stage_cfg = request.config.stages[stage_name]
+    stage_path = _required_stage_path(ctx, stage_name, stage_cfg)
+    label = f"{stage_name}/{uid}"
+    # The remote key is the file path directly, not a prefix
+    remote_prefix = _remote_prefix_for_unit(stage_cfg, uid)
+    local_path = request.project_root / stage_path / uid
+    pull_tuples = [(remote_prefix, local_path)]
+
+    # Get file size from a stage-level ls
+    try:
+        stage_remote_files = _listed_remote_files(
+            request.transport, request.remote_cfg.url, prefix=_effective_remote_base(stage_cfg).as_posix()
+        )
+    except RcloneError as exc:
+        _echo_error(f"ERROR {label}  {_transport_error_detail(exc)}")
+        return False
+
+    file_size = next((rf.size for rf in stage_remote_files if rf.key == uid), None)
+    if file_size is None:
+        _echo_error(f"ERROR {label}  missing remote target: {remote_prefix}")
+        return False
+
+    size_str = _format_size(file_size)
+    if request.dry_run:
+        _echo_info(ctx, f"PLAN {label}  1 files, {size_str} <- {request.remote_name}")
+        _echo_verbose(ctx, f"  {uid} ({size_str})")
+        return True
+
+    xfer = _observed_pull(ctx, request, label, pull_tuples)
+    if _echo_transfer_errors(label, xfer):
+        return False
+
+    checksum = compute_checksum(request.project_root / stage_path, [local_path])
+    remote_path = request.remote_cfg.url.rstrip("/") + "/" + remote_prefix
+    payload = _sync_entry_payload(request, stage_name, uid, stage_cfg, local_path, remote_path, checksum, xfer)
+    _record_transfer(request, "pull", payload)
+    _echo_info(ctx, f"PULL {label}  {xfer.files_transferred} files, {size_str} <- {request.remote_name}")
+    return True
+
+
+def _build_pull_tuples(
+    label: str, remote_files: list[RemoteFile], remote_prefix: str, local_root: Path
+) -> list[tuple[str, Path]] | None:
+    """Map remote keys to local paths, rejecting unsafe keys before any local write."""
+    pull_tuples: list[tuple[str, Path]] = []
+    for rf in remote_files:
+        try:
+            safe_key = _safe_remote_file_key(rf.key)
+        except ValueError as exc:
+            _echo_error(f"ERROR {label}  {exc}")
+            return None
+        pull_tuples.append((f"{remote_prefix}/{safe_key.as_posix()}", local_root / safe_key.as_posix()))
+    return pull_tuples
+
+
+def _pull_tree_unit(ctx: click.Context, request: _TransferRequest, stage_name: str, uid: str, abs_path: Path) -> bool:
+    """Pull a directory/subdirectory unit from its remote prefix; return False on failure."""
+    stage_cfg = request.config.stages[stage_name]
+    stage_path = _required_stage_path(ctx, stage_name, stage_cfg)
+    label = f"{stage_name}/{uid}"
+    unit_prefix = stage_path if stage_cfg.sync_by == "directory" else stage_path / uid
+    remote_prefix = _remote_prefix_for_unit(stage_cfg, uid)
+
+    # List remote files under the unit prefix (metadata keys already dropped).
+    try:
+        remote_files = _listed_remote_files(request.transport, request.remote_cfg.url, prefix=remote_prefix)
+    except RcloneError as exc:
+        _echo_error(f"ERROR {label}  {_transport_error_detail(exc)}")
+        return False
+    if not remote_files:
+        _echo_error(f"ERROR {label}  missing remote target: {remote_prefix}")
+        return False
+
+    pull_tuples = _build_pull_tuples(label, remote_files, remote_prefix, request.project_root / unit_prefix)
+    if pull_tuples is None:
+        return False
+
+    size_str = _format_size(sum(rf.size for rf in remote_files))
+    if request.dry_run:
+        _echo_info(ctx, f"PLAN {label}  {len(remote_files)} files, {size_str} <- {request.remote_name}")
+        _echo_pull_file_details(ctx, remote_files)
+        return True
+
+    xfer = _observed_pull(ctx, request, label, pull_tuples)
+    if _echo_transfer_errors(label, xfer):
+        return False
+
+    # Compute checksum from pulled files
+    checksum = compute_checksum(abs_path, sorted(lp for _, lp in pull_tuples))
+    remote_path = request.remote_cfg.url.rstrip("/") + "/" + remote_prefix
+    payload = _sync_entry_payload(request, stage_name, uid, stage_cfg, abs_path, remote_path, checksum, xfer)
+    _record_transfer(request, "pull", payload)
+    _echo_info(ctx, f"PULL {label}  {xfer.files_transferred} files, {size_str} <- {request.remote_name}")
+    _echo_pull_file_details(ctx, remote_files)
+    return True
+
+
+def _pull_unit(ctx: click.Context, request: _TransferRequest, stage_name: str, uid: str, abs_path: Path) -> bool:
+    """Pull one unit; sync_by=file goes through the direct file transfer path."""
+    if request.config.stages[stage_name].sync_by == "file":
+        return _pull_file_unit(ctx, request, stage_name, uid)
+    return _pull_tree_unit(ctx, request, stage_name, uid, abs_path)
+
+
+@main.command()
+@click.argument("unit_ids", nargs=-1)
+@click.option("--stage", default=None, help="Stage to pull from.")
+@click.option("--id", "id_value", default=None, help="Resolve units via manifest ID.")
+@click.option("--all", "all_flag", is_flag=True, help="Pull all units in all stages.")
+@click.option("--dry-run", is_flag=True, help="Show plan without downloading.")
+@click.pass_context
+def pull(
+    ctx: click.Context,
+    unit_ids: tuple[str, ...],
+    stage: str | None,
+    id_value: str | None,
+    all_flag: bool,
+    dry_run: bool,
+) -> None:
+    """Pull data units from a remote.
+
+    Resolves targets, lists remote files, downloads all of them via
+    transport, and records sync state.
+    """
+    config = _load_project_config(ctx)
+    project_root = _project_root(ctx)
+    _validate_stage_option(ctx, config, stage)
+
+    targets, pull_stages = _resolve_pull_scope(ctx, config, project_root, unit_ids, stage, id_value, all_flag)
+    if pull_stages is None and not targets:
+        return
+
+    remote_name = _resolve_remote(ctx, config, project_root, None)
+    if remote_name is None:
+        return
+    remote_cfg = config.remotes[remote_name]
+
+    transport = _acquire_transport(ctx, remote_name, remote_cfg)
+    request = _TransferRequest(
+        transport=transport,
+        remote_name=remote_name,
+        remote_cfg=remote_cfg,
+        config=config,
+        project_root=project_root,
+        state_path=_state_path(ctx),
+        dry_run=dry_run,
+    )
+
+    if pull_stages is not None:
+        targets = _list_pull_all_targets(ctx, request, pull_stages)
+        if not targets:
+            return
+    assert targets is not None
+
+    had_failure = False
+    for stage_name, uid, abs_path in targets:
+        if not _pull_unit(ctx, request, stage_name, uid, abs_path):
+            had_failure = True
+
+    if had_failure:
+        monitoring.report_failure("pull completed with errors", f"remote '{remote_name}'", command="pull")
+        ctx.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Status command
+# ---------------------------------------------------------------------------
+
+
+def _format_timestamp(iso_ts: str) -> str:
+    """Format an ISO-8601 timestamp to a short display string."""
+    try:
+        from datetime import datetime
+
+        dt = datetime.fromisoformat(iso_ts)
+        if dt.tzinfo is not None:
+            dt = dt.astimezone(tz=None)
+        return dt.strftime("%Y-%m-%d %H:%M")
+    except (ValueError, TypeError):
+        return iso_ts
+
+
+def _stage_scope(ctx: click.Context, config: ProjectConfig, stage: str | None) -> dict[str, StageConfig]:
+    """Stages to examine (ADR 0016): bare use covers bound stages and warns per
+    unbound stage; explicit --stage stays strict."""
+    if stage:
+        stages = {stage: config.stages[stage]}
+        _ensure_stages_bound(ctx, config, list(stages))
+        return stages
+    return _bound_stage_subset(ctx, config)
+
+
+def _local_units_in_scope(
+    stages: dict[str, StageConfig], project_root: Path, id_targets: set[tuple[str, str]] | None
+) -> list[tuple[str, str, Path]]:
+    """Discover local units from stage paths, honoring the --id filter."""
+    local_units: list[tuple[str, str, Path]] = []
+    for stage_name, stage_cfg in stages.items():
+        for uid, abs_path in discover_units(stage_cfg, project_root):
+            if id_targets is None or (stage_name, uid) in id_targets:
+                local_units.append((stage_name, uid, abs_path))
+    return local_units
+
+
+def _status_entry_in_scope(
+    entry: SyncEntry,
+    config: ProjectConfig,
+    stages: dict[str, StageConfig],
+    stage: str | None,
+    remote_name: str | None,
+    id_targets: set[tuple[str, str]] | None,
+) -> bool:
+    """Apply stage / bound-stage / remote / --id filters to a sync entry."""
+    if stage and entry.stage != stage:
+        return False
+    # A skipped (unbound) stage contributes no rows at all (ADR 0016);
+    # stages no longer in config still surface as remote-only.
+    if entry.stage in config.stages and entry.stage not in stages:
+        return False
+    # Scope sync-state entries to the active remote.
+    if remote_name and entry.remote != remote_name:
+        return False
+    return id_targets is None or (entry.stage, entry.unit_id) in id_targets
+
+
+def _remote_only_status_entries(
+    state: SyncState,
+    config: ProjectConfig,
+    stages: dict[str, StageConfig],
+    stage: str | None,
+    remote_name: str | None,
+    id_targets: set[tuple[str, str]] | None,
+    local_keys: set[tuple[str, str]],
+) -> list[tuple[str, str, str, SyncEntry]]:
+    """Sync-state entries whose local unit no longer exists."""
+    remote_only: list[tuple[str, str, str, SyncEntry]] = []
+    for entry in state.entries:
+        if not _status_entry_in_scope(entry, config, stages, stage, remote_name, id_targets):
+            continue
+        if (entry.stage, entry.unit_id) not in local_keys:
+            remote_only.append((entry.stage, entry.unit_id, entry.remote, entry))
+    return remote_only
+
+
+def _unit_files_and_size(abs_path: Path) -> tuple[list[Path], str]:
+    """Collect a unit's files (OS junk skipped) and format their total size."""
+    sync_files = [abs_path] if abs_path.is_file() else list_sync_files(abs_path)
+    size_str = _format_size(sum(f.stat().st_size for f in sync_files) if sync_files else 0)
+    return sync_files, size_str
+
+
+def _matching_state_entries(state: SyncState, stage_name: str, uid: str, remote_name: str | None) -> list[SyncEntry]:
+    """Sync entries for a unit, scoped to the active remote when known."""
+    matching = [e for e in state.entries if e.stage == stage_name and e.unit_id == uid]
+    if remote_name:
+        matching = [e for e in matching if e.remote == remote_name]
+    return matching
+
+
+def _echo_entry_status_rows(
+    ctx: click.Context,
+    config: ProjectConfig,
+    stage_cfg: StageConfig,
+    uid: str,
+    label: str,
+    size_str: str,
+    current_checksum: str,
+    entries: list[SyncEntry],
+) -> None:
+    """Emit a synced/stale row per sync entry for a local unit."""
+    for entry in entries:
+        direction_label = "pushed" if entry.direction == "push" else "pulled"
+        ts = _format_timestamp(entry.timestamp)
+        in_sync = current_checksum == entry.checksum and _entry_remote_path_matches_current(
+            config, stage_cfg, uid, entry
+        )
+        status_label = f"synced:{entry.remote}" if in_sync else f"stale:{entry.remote}"
+        _echo_info(ctx, f"{status_label}  {label}  {size_str}  {direction_label} {ts}")
+
+
+def _echo_local_unit_status(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    state: SyncState,
+    remote_name: str | None,
+    stage_name: str,
+    uid: str,
+    abs_path: Path,
+) -> None:
+    """Classify one local unit against sync state and emit its status rows."""
+    stage_cfg = config.stages[stage_name]
+    stage_path = _required_stage_path(ctx, stage_name, stage_cfg)
+    label = f"{stage_name}/{uid}"
+    sync_files, size_str = _unit_files_and_size(abs_path)
+
+    matching_entries = _matching_state_entries(state, stage_name, uid, remote_name)
+    if not matching_entries:
+        # No sync entry for the active remote means this local unit has not
+        # been synchronized to that remote.
+        _echo_info(ctx, f"local-only  {label}  {size_str}  never pushed")
+        return
+
+    # For file mode, use stage dir as checksum base
+    checksum_base = project_root / stage_path if stage_cfg.sync_by == "file" else abs_path
+    current_checksum = compute_checksum(checksum_base, sync_files) if sync_files else ""
+    _echo_entry_status_rows(ctx, config, stage_cfg, uid, label, size_str, current_checksum, matching_entries)
+
+
+@main.command()
+@click.option("--stage", default=None, help="Filter by stage.")
+@click.option("--id", "id_value", default=None, help="Resolve units via manifest ID.")
+@click.pass_context
+def status(
+    ctx: click.Context,
+    stage: str | None,
+    id_value: str | None,
+) -> None:
+    """Show sync status of data units.
+
+    Compares local state against sync_state.json to classify each unit
+    as synced, local-only, remote-only, or stale. Read-only — no files
+    are modified and no network calls are made by default.
+    """
+    config = _load_project_config(ctx)
+    project_root = _project_root(ctx)
+    _validate_stage_option(ctx, config, stage)
+
+    remote_name = _resolve_remote(ctx, config, project_root, None)
+    if remote_name is None:
+        return
+
+    state = load_state(_state_path(ctx))
+    stages = _stage_scope(ctx, config, stage)
+
+    id_targets: set[tuple[str, str]] | None = None
+    if id_value:
+        id_targets = set(_resolve_manifest_pairs_or_exit(ctx, config, project_root, id_value, stage))
+
+    local_units = _local_units_in_scope(stages, project_root, id_targets)
+    local_keys = {(sn, uid) for sn, uid, _ in local_units}
+    remote_only_entries = _remote_only_status_entries(state, config, stages, stage, remote_name, id_targets, local_keys)
+
+    for stage_name, uid, abs_path in local_units:
+        _echo_local_unit_status(ctx, config, project_root, state, remote_name, stage_name, uid, abs_path)
+
+    for stage_name, uid, rname, entry in remote_only_entries:
+        label = f"{stage_name}/{uid}"
+        direction_label = "pushed" if entry.direction == "push" else "pulled"
+        ts = _format_timestamp(entry.timestamp)
+        size_str = _format_size(entry.total_bytes) if entry.total_bytes else "--"
+        _echo_info(ctx, f"remote-only:{rname}  {label}  {size_str}  {direction_label} {ts}")
+
+
+# ---------------------------------------------------------------------------
+# Diff command
+# ---------------------------------------------------------------------------
+
+
+def _deleted_push_targets(state: SyncState, stages: set[str], seen: set[tuple[str, str]]) -> list[tuple[str, str]]:
+    """Sync-state push entries whose unit no longer exists locally."""
+    extra: list[tuple[str, str]] = []
+    for entry in state.entries:
+        if entry.direction != "push" or entry.stage not in stages:
+            continue
+        key = (entry.stage, entry.unit_id)
+        if key not in seen:
+            seen.add(key)
+            extra.append(key)
+    return extra
+
+
+def _diff_stage_targets(
+    ctx: click.Context, config: ProjectConfig, project_root: Path, state: SyncState, stage: str
+) -> list[tuple[str, str]]:
+    stage_cfg = config.stages[stage]
+    _ensure_stage_bound(ctx, stage, stage_cfg)
+    targets = [(stage, uid) for uid, _ in discover_units(stage_cfg, project_root)]
+    targets.extend(_deleted_push_targets(state, {stage}, set(targets)))
+    return targets
+
+
+def _diff_bare_targets(
+    ctx: click.Context, config: ProjectConfig, project_root: Path, state: SyncState
+) -> list[tuple[str, str]]:
+    # ADR 0016: bare diff covers bound stages and warns per unbound stage.
+    bound = _bound_stage_subset(ctx, config)
+    targets: list[tuple[str, str]] = []
+    for stage_name, stage_cfg in bound.items():
+        for uid, _ in discover_units(stage_cfg, project_root):
+            targets.append((stage_name, uid))
+    targets.extend(_deleted_push_targets(state, set(bound), set(targets)))
+    return targets
+
+
+def _resolve_diff_targets(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    state: SyncState,
+    unit_id: str | None,
+    stage: str | None,
+) -> list[tuple[str, str]]:
+    """Resolve diff targets; deleted-but-pushed units stay visible."""
+    if unit_id:
+        if not stage:
+            _echo_error("Error: --stage is required when specifying UNIT_ID.")
+            ctx.exit(1)
+            return []
+        _ensure_stage_bound(ctx, stage, config.stages[stage])
+        return [(stage, unit_id)]
+    if stage:
+        return _diff_stage_targets(ctx, config, project_root, state, stage)
+    return _diff_bare_targets(ctx, config, project_root, state)
+
+
+def _last_push_entry(state: SyncState, stage_name: str, uid: str) -> SyncEntry | None:
+    for entry in reversed(state.entries):
+        if entry.stage == stage_name and entry.unit_id == uid and entry.direction == "push":
+            return entry
+    return None
+
+
+def _echo_snapshot_diff(
+    ctx: click.Context, label: str, current_files: dict[str, int], prev_files: dict[str, int]
+) -> None:
+    """Detailed per-file diff between the local tree and the last push snapshot."""
+    for path in sorted(set(current_files) | set(prev_files)):
+        if path in current_files and path in prev_files:
+            if current_files[path] != prev_files[path]:
+                _echo_info(ctx, f"modified  {label}/{path}")
+        elif path in current_files:
+            _echo_info(ctx, f"added     {label}/{path}")
+        else:
+            _echo_info(ctx, f"deleted   {label}/{path}")
+
+
+def _echo_unit_diff(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    state: SyncState,
+    stage_name: str,
+    uid: str,
+) -> None:
+    """Diff one unit against its last push entry and emit changed rows."""
+    stage_cfg = config.stages[stage_name]
+    stage_path = _required_stage_path(ctx, stage_name, stage_cfg)
+    label = f"{stage_name}/{uid}"
+    abs_path = _resolve_unit_path(stage_cfg, project_root, uid)
+
+    # Collect all files under the unit (schema-free); OS junk is skipped.
+    sync_files = [abs_path] if abs_path.is_file() else list_sync_files(abs_path)
+    checksum_base = project_root / stage_path if stage_cfg.sync_by == "file" else abs_path
+    current_files = {str(f.relative_to(checksum_base)): f.stat().st_size for f in sync_files}
+
+    last_push = _last_push_entry(state, stage_name, uid)
+    if last_push is None:
+        # Never pushed — all files shown as added
+        for path in sorted(current_files):
+            _echo_info(ctx, f"added     {label}/{path}")
+        return
+
+    if last_push.file_snapshot is None:
+        # Old sync entry without file_snapshot — overall comparison only
+        if compute_checksum(checksum_base, sync_files) != last_push.checksum:
+            _echo_info(ctx, f"modified  {label}  (re-push to enable detailed diff)")
+        return
+
+    _echo_snapshot_diff(ctx, label, current_files, last_push.file_snapshot)
+
+
+@main.command("diff")
+@click.argument("unit_id", required=False, default=None)
+@click.option("--stage", default=None, help="Filter by stage.")
+@click.pass_context
+def diff(
+    ctx: click.Context,
+    unit_id: str | None,
+    stage: str | None,
+) -> None:
+    """Show what changed locally since last push.
+
+    Compares the current local filesystem state against the file snapshot
+    recorded in sync_state.json during the last push.  Shows modified
+    (size changed), added (new file), and deleted (removed file) entries.
+    Schema include/exclude filters are applied — excluded files never
+    appear.  A never-pushed unit lists every file as added.  When
+    nothing changed, output is empty.
+    """
+    config = _load_project_config(ctx)
+    project_root = _project_root(ctx)
+    _validate_stage_option(ctx, config, stage)
+
+    # Sync state feeds both target resolution and per-unit diff logic.
+    state = load_state(_state_path(ctx))
+    targets = _resolve_diff_targets(ctx, config, project_root, state, unit_id, stage)
+
+    for stage_name, uid in targets:
+        _echo_unit_diff(ctx, config, project_root, state, stage_name, uid)
+
+
+# ---------------------------------------------------------------------------
+# Ls helpers
+# ---------------------------------------------------------------------------
+
+
+def _format_size_long(size_bytes: int) -> str:
+    """Format byte count as a right-aligned human-readable size for --long."""
+    if size_bytes >= 1024 * 1024 * 1024:
+        return f"{size_bytes / (1024**3):.1f} GB"
+    if size_bytes >= 1024 * 1024:
+        return f"{size_bytes / (1024**2):.1f} MB"
+    if size_bytes >= 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    return f"{size_bytes} B"
+
+
+def _build_tree(entries: list[str]) -> list[str]:
+    """Build a tree-view of path entries using branch characters.
+
+    *entries* is a list of ``/``-separated relative paths.  Returns lines
+    ready for printing, using ``├──``, ``└──``, and ``│`` characters.
+    """
+    # Build nested dict
+    tree: dict[str, Any] = {}
+    for entry in sorted(entries):
+        parts = entry.split("/")
+        node = tree
+        for p in parts:
+            node = node.setdefault(p, {})
+
+    lines: list[str] = []
+    _render_tree(tree, lines, prefix="")
+    return lines
+
+
+def _render_tree(
+    node: dict[str, Any],
+    lines: list[str],
+    prefix: str,
+) -> None:
+    """Recursively render tree dict into output lines."""
+    items = list(node.items())
+    for i, (name, children) in enumerate(items):
+        is_last = i == len(items) - 1
+        connector = "└── " if is_last else "├── "
+        lines.append(f"{prefix}{connector}{name}")
+        extension = "    " if is_last else "│   "
+        _render_tree(children, lines, prefix + extension)
+
+
+def _resolve_ls_targets(
+    ctx: click.Context,
+    config: ProjectConfig,
+    project_root: Path,
+    unit_id: str | None,
+    stage: str | None,
+    id_value: str | None,
+) -> list[tuple[str, str | None]]:
+    """Resolve ls targets to (stage_name, unit_id_or_None) pairs.
+
+    When *unit_id* is given, returns a single target with that unit.
+    When *id_value* is given, resolves via manifest.
+    Otherwise returns all stages with unit_id=None.
+    """
+    targets: list[tuple[str, str | None]] = []
+
+    if unit_id:
+        if not stage:
+            _echo_error("Error: --stage is required when specifying a UNIT_ID.")
+            ctx.exit(1)
+            return []
+        if stage not in config.stages:
+            _echo_error(f"Error: stage '{stage}' not found in config.")
+            ctx.exit(1)
+            return []
+        targets.append((stage, unit_id))
+        return targets
+
+    if id_value:
+        targets.extend(_resolve_manifest_pairs_or_exit(ctx, config, project_root, id_value, stage))
+        return targets
+
+    # Default: all stages
+    stages = {stage: config.stages[stage]} if stage else config.stages
+    for stage_name in stages:
+        targets.append((stage_name, None))
+    return targets
+
+
+def _ls_remote_files_or_exit(
+    ctx: click.Context,
+    transport: RcloneTransport,
+    remote_cfg: RemoteConfig,
+    remote_name: str,
+    prefix: str,
+) -> list[RemoteFile]:
+    """List remote files under *prefix*, exiting with an error on failure."""
+    try:
+        return _listed_remote_files(transport, remote_cfg.url, prefix=prefix)
+    except RcloneError as exc:
+        _echo_error(f"Error: failed to list remote '{remote_name}': {_transport_error_detail(exc)}")
+        ctx.exit(1)
+        raise AssertionError("unreachable") from exc
+
+
+def _ls_unit_prefix(stage_cfg: StageConfig, stage_name: str, target_uid: str) -> str | None:
+    """Remote prefix for one unit, or None when the unit cannot exist."""
+    remote_base = _effective_remote_base(stage_cfg)
+    if stage_cfg.sync_by == "directory":
+        expected_uid = stage_cfg.path.name if stage_cfg.path is not None else stage_name
+        return remote_base.as_posix() if target_uid == expected_uid else None
+    return (remote_base / target_uid).as_posix()
+
+
+def _echo_unit_files(
+    ctx: click.Context,
+    label: str,
+    remote_files: list[RemoteFile],
+    *,
+    tree_flag: bool,
+    long_flag: bool,
+) -> None:
+    """Print the files of one unit in plain, --tree, or --long form."""
+    _echo_info(ctx, f"{label}/")
+    if tree_flag:
+        for line in _build_tree([rf.key for rf in remote_files]):
+            _echo_info(ctx, line)
+    elif long_flag:
+        for rf in remote_files:
+            size_str = _format_size_long(rf.size)
+            ts = rf.last_modified or ""
+            _echo_info(ctx, f"  {size_str:>10}  {ts:>16}  {rf.key}")
+    else:
+        for rf in remote_files:
+            _echo_info(ctx, f"  {rf.key}")
+            _echo_verbose(ctx, f"    size: {_format_size_long(rf.size)}")
+
+
+def _echo_directory_stage(
+    ctx: click.Context,
+    stage_name: str,
+    remote_files: list[RemoteFile],
+    *,
+    tree_flag: bool,
+    long_flag: bool,
+) -> None:
+    """Print a sync_by=directory stage: the whole stage is one unit."""
+    if tree_flag:
+        _echo_info(ctx, f"{stage_name}/")
+        for line in _build_tree([rf.key for rf in remote_files]):
+            _echo_info(ctx, line)
+    elif long_flag:
+        size_str = _format_size_long(sum(rf.size for rf in remote_files))
+        _echo_info(ctx, f"  {stage_name}/  {len(remote_files)} files  {size_str}")
+    else:
+        _echo_info(ctx, f"  {stage_name}/  ({len(remote_files)} files)")
+        for rf in remote_files:
+            _echo_verbose(ctx, f"    {rf.key}  {_format_size_long(rf.size)}")
+
+
+def _echo_subdirectory_tree(ctx: click.Context, stage_name: str, units: dict[str, list[RemoteFile]]) -> None:
+    """Print units of a sync_by=subdirectory stage as a tree."""
+    _echo_info(ctx, f"{stage_name}/")
+    unit_names = sorted(units)
+    for i, uid in enumerate(unit_names):
+        is_last = i == len(unit_names) - 1
+        _echo_info(ctx, f"{'└── ' if is_last else '├── '}{uid}/")
+        # Rebase keys to be relative to the unit
+        rel_paths = [rf.key.split("/", 1)[1] for rf in units[uid] if "/" in rf.key]
+        extension = "    " if is_last else "│   "
+        for line in _build_tree(rel_paths):
+            _echo_info(ctx, f"{extension}{line}")
+
+
+def _echo_subdirectory_stage(
+    ctx: click.Context,
+    stage_name: str,
+    remote_files: list[RemoteFile],
+    *,
+    tree_flag: bool,
+    long_flag: bool,
+) -> None:
+    """Print a sync_by=subdirectory stage grouped into units by first path part."""
+    units: dict[str, list[RemoteFile]] = {}
+    for rf in remote_files:
+        units.setdefault(rf.key.split("/")[0], []).append(rf)
+
+    if tree_flag:
+        _echo_subdirectory_tree(ctx, stage_name, units)
+    elif long_flag:
+        for uid in sorted(units):
+            size_str = _format_size_long(sum(rf.size for rf in units[uid]))
+            _echo_info(ctx, f"  {stage_name}/{uid}  {len(units[uid])} files  {size_str}")
+    else:
+        for uid in sorted(units):
+            _echo_info(ctx, f"  {stage_name}/{uid}  ({len(units[uid])} files)")
+            for rf in units[uid]:
+                _echo_verbose(ctx, f"    {rf.key}  {_format_size_long(rf.size)}")
+
+
+def _echo_file_stage(
+    ctx: click.Context,
+    stage_name: str,
+    remote_files: list[RemoteFile],
+    *,
+    tree_flag: bool,
+    long_flag: bool,
+) -> None:
+    """Print a sync_by=file stage: each top-level file is one unit."""
+    file_units = [rf for rf in remote_files if len([part for part in rf.key.split("/") if part]) == 1]
+    if tree_flag:
+        _echo_info(ctx, f"{stage_name}/")
+        for line in _build_tree([rf.key for rf in file_units]):
+            _echo_info(ctx, line)
+    elif long_flag:
+        for rf in file_units:
+            _echo_info(ctx, f"  {stage_name}/{rf.key}  {_format_size_long(rf.size)}  {rf.last_modified or ''}")
+    else:
+        for rf in file_units:
+            _echo_info(ctx, f"  {stage_name}/{rf.key}")
+            _echo_verbose(ctx, f"    size: {_format_size_long(rf.size)}")
+
+
+def _ls_transport_or_exit(
+    ctx: click.Context, config: ProjectConfig, project_root: Path
+) -> tuple[str, RemoteConfig, RcloneTransport] | None:
+    """Resolve the active remote and its transport for ls, exiting on hard errors."""
+    remote_name = _resolve_remote(ctx, config, project_root, None)
+    if remote_name is None:
+        return None
+    remote_cfg = config.remotes[remote_name]
+
+    # rclone is required for every transport operation (G3 baseline gating).
+    if not is_available():
+        _echo_error(f"Error: {RCLONE_INSTALL_MSG}")
+        ctx.exit(1)
+        return None
+
+    try:
+        transport = get_transport(remote_cfg)
+    except ValueError as exc:
+        _echo_error(f"Error: {exc}")
+        ctx.exit(1)
+        return None
+    if not _preflight_remote_config(ctx, remote_cfg):
+        return None
+
+    _echo_verbose(ctx, f"Using remote '{remote_name}' [{remote_cfg.remote_type}] at {remote_cfg.url}")
+    if remote_cfg.remote_type == "s3":
+        _echo_verbose(ctx, f"  backend={transport.backend_name}")
+    return remote_name, remote_cfg, transport
+
+
+# ---------------------------------------------------------------------------
+# Ls command
+# ---------------------------------------------------------------------------
+
+
+@main.command("ls")
+@click.argument("unit_id", required=False, default=None)
+@click.option("--stage", default=None, help="Filter by stage.")
+@click.option("--id", "id_value", default=None, help="Resolve units via manifest ID.")
+@click.option("--tree", "tree_flag", is_flag=True, help="Show directory tree view.")
+@click.option("--long", "long_flag", is_flag=True, help="Show sizes and timestamps.")
+@click.pass_context
+def ls(
+    ctx: click.Context,
+    unit_id: str | None,
+    stage: str | None,
+    id_value: str | None,
+    tree_flag: bool,
+    long_flag: bool,
+) -> None:
+    """List data units or files on a remote.
+
+    Queries the active remote via the transport backend. When UNIT_ID is
+    given with --stage, lists files within that specific unit. Otherwise
+    lists data units per stage.
+    """
+    config = _load_project_config(ctx)
+    if config is None:
+        return
+    project_root = _project_root(ctx)
+    _validate_stage_option(ctx, config, stage)
+
+    resolved = _ls_transport_or_exit(ctx, config, project_root)
+    if resolved is None:
+        return
+    remote_name, remote_cfg, transport = resolved
+
+    targets = _resolve_ls_targets(ctx, config, project_root, unit_id, stage, id_value)
+    for stage_name, target_uid in targets:
+        stage_cfg = config.stages[stage_name]
+
+        if target_uid is not None:
+            # List files within a specific unit
+            prefix = _ls_unit_prefix(stage_cfg, stage_name, target_uid)
+            remote_files = (
+                [] if prefix is None else _ls_remote_files_or_exit(ctx, transport, remote_cfg, remote_name, prefix)
+            )
+            if not remote_files:
+                _echo_info(ctx, f"{stage_name}/{target_uid}: no files on remote")
+                continue
+            _echo_unit_files(ctx, f"{stage_name}/{target_uid}", remote_files, tree_flag=tree_flag, long_flag=long_flag)
+            continue
+
+        # List units within a stage (discover from remote)
+        prefix = _effective_remote_base(stage_cfg).as_posix()
+        remote_files = _ls_remote_files_or_exit(ctx, transport, remote_cfg, remote_name, prefix)
+        if remote_files:
+            echo_stage = {
+                "directory": _echo_directory_stage,
+                "subdirectory": _echo_subdirectory_stage,
+                "file": _echo_file_stage,
+            }[stage_cfg.sync_by]
+            echo_stage(ctx, stage_name, remote_files, tree_flag=tree_flag, long_flag=long_flag)
+
+
+@main.command()
+@click.option("--id", "id_value", default=None, help="Expand a manifest ID to its units + resolved paths.")
+@click.option("--stage", "stage_name", default=None, help="Expand a single stage to its discovered units.")
+@click.option(
+    "--direction",
+    type=click.Choice(["LR", "TD"]),
+    default="LR",
+    help="Mermaid flow direction (default: LR).",
+)
+@click.option(
+    "--output", "output_path", default=None, type=click.Path(), help="Write diagram to PATH instead of stdout."
+)
+@click.pass_context
+def flow(
+    ctx: click.Context,
+    id_value: str | None,
+    stage_name: str | None,
+    direction: str,
+    output_path: str | None,
+) -> None:
+    """Emit a Mermaid data-flow diagram derived from the live project config.
+
+    Dry-run only: reads config/manifest/sync-state existence and never
+    touches rclone or mutates state. Default view is stage-level; pass --id or
+    --stage to expand a slice to its units and resolved paths.
+    """
+    config = _load_project_config(ctx)
+    project_root = _project_root(ctx)
+
+    local_config = _load_active_local_config(ctx)
+    active = local_config.active_remote if local_config.active_remote in config.remotes else None
+    has_state = _state_path(ctx).exists()
+
+    expanded_units: dict[str, list[tuple[str, str | None, str | None]]] = {}
+
+    if id_value is not None:
+        if config.manifest is None:
+            _echo_error("Error: --id requires a manifest section in forest.yaml.")
+            ctx.exit(1)
+        manifest = load_manifest(project_root / config.manifest.file)
+        for stage, uid, local_path, remote_path in resolve_paths(config, manifest, id_value, stage_name):
+            expanded_units.setdefault(stage, []).append((uid, str(local_path), remote_path))
+    elif stage_name is not None:
+        if stage_name not in config.stages:
+            _echo_error(f"Error: unknown stage '{stage_name}'.")
+            ctx.exit(1)
+        for uid, abs_path in discover_units(config.stages[stage_name], project_root):
+            expanded_units.setdefault(stage_name, []).append((uid, str(abs_path), None))
+
+    nodes, edges = build_graph(
+        config,
+        active_remote=active,
+        has_state=has_state,
+        expanded_units=expanded_units or None,
+        key_outputs=None,
+    )
+    text = render_mermaid(nodes, edges, direction=direction)
+
+    if output_path:
+        Path(output_path).write_text(text + "\n")
+        _echo_info(ctx, f"Wrote {output_path}")
+    else:
+        click.echo(text)