obris-cli 0.6.2__tar.gz → 0.7.0__tar.gz

{obris_cli-0.6.2 → obris_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: obris-cli
-Version: 0.6.2
+Version: 0.7.0
 Summary: Save, organize, and access your knowledge from the command line
 Project-URL: Homepage, https://obris.ai
 Project-URL: Repository, https://github.com/obris-dev/obris

{obris_cli-0.6.2 → obris_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "obris-cli"
-version = "0.6.2"
+version = "0.7.0"
 description = "Save, organize, and access your knowledge from the command line"
 
 requires-python = ">=3.10"

obris_cli-0.7.0/src/obris/commands/sync_config.py

@@ -0,0 +1,290 @@
+"""Per-checkout sync configuration subcommands.
+
+Hosts ``exclude`` / ``include`` / ``untrack`` — commands that modify
+state-file metadata for a synced directory. Kept out of
+``commands.sync`` so the sync group definition + invocation logic
+stays under the 300-line cap and these subcommands stay together
+because they share the ``_states_for_current_dir`` resolver.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import pathspec
+from pathspec.patterns.gitwildmatch import GitWildMatchPattern
+
+from obris.sync.exclusions import ExclusionMatcher
+from obris.sync.state import SyncState
+
+
+def _states_for_current_dir(path):
+    """Return ``(sync_dir, states)`` for ``path``, exiting cleanly if unsynced."""
+    sync_dir = Path(path).resolve()
+    states = SyncState.find_all_for_path(sync_dir)
+    if not states:
+        raise SystemExit(f"No synced topic found for {sync_dir}/. Run 'obris sync --topic <id>' first.")
+    return sync_dir, states
+
+
+def register(sync):
+    """Attach the config subcommands to the given Click group."""
+
+    @sync.command("exclude")
+    @click.argument("patterns", nargs=-1)
+    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
+    @click.option("--list", "list_only", is_flag=True, help="Print current settings")
+    def sync_exclude(patterns, path, list_only):
+        """Stop syncing files that match a pattern.
+
+        \b
+          obris sync exclude scratch/          # an entire folder
+          obris sync exclude notes.draft.md    # a specific file
+          obris sync exclude '*.draft.md'      # all drafts
+          obris sync exclude --list            # show current settings
+
+        Wins over any prior ``obris sync include`` for the same
+        pattern, so the user-facing rule stays simple: "the last
+        thing you said is what happens."
+        """
+        sync_dir, states = _states_for_current_dir(path)
+
+        if list_only:
+            if patterns:
+                raise click.UsageError("Cannot combine --list with patterns.")
+            _list_settings(states)
+            return
+
+        if not patterns:
+            raise click.UsageError("Provide one or more patterns, or use --list.")
+
+        results = _apply_pattern_action(states, patterns, action="exclude", sync_dir=sync_dir)
+        _emit_outcomes(sync_dir, results, action="exclude")
+
+    @sync.command("include")
+    @click.argument("patterns", nargs=-1, required=True)
+    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
+    def sync_include(patterns, path):
+        """Force a file or pattern to sync, overriding any exclusion.
+
+        Use this whenever ``obris sync`` says a file is being skipped
+        and you actually want it. Works whether the file was being
+        excluded by a built-in default or by a prior
+        ``obris sync exclude``.
+
+        \b
+          obris sync include .env.example      # sync this even though
+                                                #  .env.* is excluded by default
+          obris sync include scratch/draft.md  # sync one file inside an
+                                                #  excluded folder
+          obris sync include '*.draft.md'      # un-exclude a pattern you
+                                                #  previously excluded
+
+        Wins over any prior ``obris sync exclude`` for the same pattern
+        — last call wins.
+        """
+        sync_dir, states = _states_for_current_dir(path)
+        results = _apply_pattern_action(states, patterns, action="include", sync_dir=sync_dir)
+        _emit_outcomes(sync_dir, results, action="include")
+
+    @sync.command("untrack")
+    @click.argument("targets", nargs=-1, required=True)
+    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
+    def sync_untrack(targets, path):
+        """Stop syncing items without deleting either side.
+
+        Each TARGET is a knowledge ID or a tracked filename (basename).
+        Removes the sync link; both the local file and the remote item stay
+        in place. Subsequent 'obris sync' calls will not re-pull these items.
+
+        \b
+          obris sync untrack abc123
+          obris sync untrack notes.md draft.md
+
+        Re-link later with 'obris sync link <file> -i <id>' or 'obris sync add'.
+        Permanently delete the remote with 'obris knowledge delete <id>'.
+        """
+        sync_dir, states = _states_for_current_dir(path)
+
+        untracked = []
+        not_found = []
+        for target in targets:
+            matches = _resolve_target(target, states)
+            if not matches:
+                not_found.append(target)
+                continue
+            if len(matches) > 1:
+                click.echo(f"Ambiguous: '{target}' matches multiple tracked items:")
+                for state, kid in matches:
+                    entry = state.get(kid)
+                    click.echo(f"  {kid}  ({entry.filename})")
+                click.echo("  Re-run with the specific knowledge ID.")
+                raise SystemExit(1)
+            state, kid = matches[0]
+            entry = state.get(kid)
+            state.untrack(kid)
+            state.mark_unlinked(kid)
+            state.save()
+            untracked.append((kid, entry.filename))
+
+        if untracked:
+            click.echo(f"Untracked {len(untracked)} item(s):")
+            for kid, name in untracked:
+                click.echo(f"  {name}  ({kid})")
+            click.echo(f"  Local files and remote items unchanged in {sync_dir}/.")
+        if not_found:
+            click.echo(f"Not tracked: {', '.join(not_found)}", err=True)
+            raise SystemExit(1)
+
+
+def _apply_pattern_action(states, patterns, *, action, sync_dir):
+    """Apply ``exclude`` or ``include`` to each pattern across all states.
+
+    Returns ``[(pattern, outcome)]`` where outcome is one of
+    ``now_skipped``, ``now_synced``, ``already_skipped``,
+    ``already_synced``, or ``no_effect``.
+
+    Strict inverses with last-call-wins semantics *and* exact-cancel:
+    when the new action's inverse is already in state we simply remove
+    it instead of layering an opposite on top. Net effect per pattern:
+
+    - prior ``foo`` + ``include foo``   → state minus ``foo``
+    - prior ``!foo`` + ``exclude foo``  → state minus ``!foo``
+    - empty + ``include foo``           → state plus ``!foo`` (only if
+                                           the pattern actually matches
+                                           a currently-excluded local
+                                           file; otherwise ``no_effect``
+                                           with no state change)
+    - empty + ``exclude foo``           → state plus ``foo``
+
+    Keeps the state at most one entry per pattern, no leftover
+    re-include or exclude after a toggle, and no state bloat from
+    ``include`` calls that wouldn't have changed anything.
+    """
+    outcomes = []
+    for state, _tid in states:
+        for pat in patterns:
+            negated = f"!{pat}"
+            current = list(state.exclude_patterns)
+            if action == "exclude":
+                if negated in current:
+                    # Cancel a prior include — just remove the override,
+                    # don't also add the exclude. Defaults re-cover the
+                    # path if the override existed to override one; if
+                    # not, both calls were no-ops on observable behavior.
+                    state.remove_excludes([negated])
+                    state.save()
+                    outcomes.append((pat, "now_skipped"))
+                elif pat in current:
+                    outcomes.append((pat, "already_skipped"))
+                else:
+                    state.add_excludes([pat])
+                    state.save()
+                    outcomes.append((pat, "now_skipped"))
+            else:
+                if pat in current:
+                    # Cancel a prior exclude — defaults take over.
+                    state.remove_excludes([pat])
+                    state.save()
+                    outcomes.append((pat, "now_synced"))
+                elif negated in current:
+                    outcomes.append((pat, "already_synced"))
+                elif _include_has_effect(sync_dir, pat, current):
+                    state.add_excludes([negated])
+                    state.save()
+                    outcomes.append((pat, "now_synced"))
+                else:
+                    # No currently-excluded file matches this pattern;
+                    # adding ``!pat`` would be state bloat with zero
+                    # observable effect. Warn and leave state alone.
+                    outcomes.append((pat, "no_effect"))
+    return outcomes
+
+
+def _include_has_effect(sync_dir: Path, pattern: str, current_excludes: list[str]) -> bool:
+    """Return True if any local file currently excluded would match ``pattern``.
+
+    Conservative: only files that physically exist under ``sync_dir``
+    count. A pattern aimed at a file that doesn't exist yet is treated
+    as no-op — the user can re-run after the file lands. Walks
+    ``sync_dir`` once per call; cost is negligible compared to a real
+    sync's network round trips.
+    """
+    matcher = ExclusionMatcher(sync_dir, state_excludes=current_excludes)
+    pattern_spec = pathspec.PathSpec.from_lines(GitWildMatchPattern, [pattern])
+    for path in Path(sync_dir).rglob("*"):
+        if path.is_dir() or path.is_symlink():
+            continue
+        rel = path.relative_to(sync_dir).as_posix()
+        if matcher.excludes(rel) and pattern_spec.match_file(rel):
+            return True
+    return False
+
+
+def _emit_outcomes(sync_dir, results, *, action):
+    """User-facing summary. No mention of state mechanics or `!pattern`."""
+    by_outcome: dict[str, set[str]] = {}
+    for pat, outcome in results:
+        by_outcome.setdefault(outcome, set()).add(pat)
+
+    changed_any = False
+    if action == "exclude":
+        if by_outcome.get("now_skipped"):
+            click.echo(f"Skipping: {', '.join(sorted(by_outcome['now_skipped']))}")
+            changed_any = True
+        if by_outcome.get("already_skipped"):
+            click.echo(f"Already skipping: {', '.join(sorted(by_outcome['already_skipped']))}")
+    else:
+        if by_outcome.get("now_synced"):
+            click.echo(f"Now syncing: {', '.join(sorted(by_outcome['now_synced']))}")
+            changed_any = True
+        if by_outcome.get("already_synced"):
+            click.echo(f"Already syncing: {', '.join(sorted(by_outcome['already_synced']))}")
+        if by_outcome.get("no_effect"):
+            pats = sorted(by_outcome["no_effect"])
+            click.echo(f"No matching skipped file(s) for: {', '.join(pats)}", err=True)
+            click.echo("  Nothing to include. Run again after the file appears, or check spelling.")
+
+    if changed_any:
+        click.echo(f"  Takes effect on next 'obris sync' in {sync_dir}/.")
+
+
+def _list_settings(states):
+    """Print currently-configured rules for each state, grouped by intent."""
+    for state, tid in states:
+        current = state.exclude_patterns
+        header = f"Settings for {tid}:" if len(states) > 1 else "Current settings:"
+        click.echo(header)
+        if not current:
+            click.echo("  (none — built-in defaults apply)")
+            continue
+        skips = [p for p in current if not p.startswith("!")]
+        forced_syncs = [p[1:] for p in current if p.startswith("!")]
+        if skips:
+            click.echo("  Skipping:")
+            for p in skips:
+                click.echo(f"    {p}")
+        if forced_syncs:
+            click.echo("  Always syncing:")
+            for p in forced_syncs:
+                click.echo(f"    {p}")
+
+
+def _resolve_target(target, states):
+    """Resolve ``target`` (kid or filename) to a list of (state, kid) matches.
+
+    Filename lookup is by basename only (matches TrackedItem.filename).
+    Returns a list because the same filename can exist under different
+    topics in the same dir; the caller decides whether to error on
+    ambiguity.
+    """
+    matches = []
+    for state, _tid in states:
+        if state.is_tracked(target):
+            matches.append((state, target))
+            continue
+        kid, _entry = state.find_by_filename(target)
+        if kid:
+            matches.append((state, kid))
+    return matches

{obris_cli-0.6.2 → obris_cli-0.7.0}/src/obris/sync/engine/run.py

@@ -143,9 +143,15 @@ def run_sync(
         if filter_item_ids and item.id not in filter_item_ids:
             continue
 
+        # On a dry-run pass, ``reconcile_topic_dirs`` deliberately doesn't
+        # call ``state.set_topic_dir`` (no side effects on the local state
+        # file), so ``state.get_topic_dir`` returns None for any subtopic
+        # that the live run would create. Fall back to the desired map
+        # the manifest already gave us, otherwise dry-run output prints
+        # bare basenames with no parent directory context.
         item_rel = state.get_topic_dir(item.topic_id) if item.topic_id else ""
         if item_rel is None:
-            item_rel = ""
+            item_rel = desired_topic_dirs.get(item.topic_id, "") if item.topic_id else ""
 
         if state.is_tracked(item.id):
             entry = state.get(item.id)

{obris_cli-0.6.2 → obris_cli-0.7.0}/src/obris/sync/exclusions.py

@@ -1,17 +1,19 @@
 """File-level exclusion matcher for sync.
 
-Combines three pattern sources, all gitignore-style (``pathspec``'s
-``gitwildmatch``):
-
-1. **Built-in defaults** — always applied, hardcoded in this module.
-   Hides VCS metadata, dependency dirs, OS / editor cruft.
-2. **``.obrisignore``** — user-authored, lives at the sync-dir root.
-   The CLI reads it; it never writes to it.
-3. **State-level excludes** — per-checkout, set via
-   ``obris sync exclude``. Plumbed through ``state_excludes`` so this
-   module has no opinion on where they're persisted.
-
-Supports gitignore semantics including ``!pattern`` re-includes.
+Combines two pattern sources, evaluated in order, gitignore-style
+(``pathspec``'s ``gitwildmatch``):
+
+1. **Built-in defaults** — hardcoded in this module. Hides VCS
+   metadata, dependency dirs, OS / editor cruft, and credential-shaped
+   files.
+2. **State-level rules** — set via ``obris sync exclude`` and
+   ``obris sync include``. Stored as a list of patterns on each
+   ``SyncState``; ``!pattern`` entries are re-includes that override
+   the defaults. The CLI is the only writer.
+
+Last match wins (gitignore semantics), so state-level rules can
+always override defaults. Users never hand-edit a config file —
+state is owned by the CLI.
 """
 
 from __future__ import annotations
@@ -22,6 +24,11 @@ import pathspec
 from pathspec.patterns.gitwildmatch import GitWildMatchPattern
 
 DEFAULT_EXCLUDES = [
+    # Obris's own in-dir state. Lives at ``<sync_dir>/.obris/`` and is
+    # never knowledge content. Self-excludes to avoid an infinite-loop
+    # of "the engine sees state files, would push them, server stores
+    # them, sync sees the new items..."
+    ".obris/",
     # VCS
     ".git/",
     ".hg/",
@@ -51,21 +58,22 @@ DEFAULT_EXCLUDES = [
     # Temp
     "*.tmp",
     "*.bak",
+    # Secrets — common files / dirs that hold credentials. Kept narrow
+    # to literal known-bad paths instead of a blanket dotfile rule so
+    # AI-tool config dirs (.claude/, .cursor/, .github/, etc.) keep
+    # syncing. Users can override any default with
+    # ``obris sync include <pattern>``.
+    ".env",
+    ".env.*",
+    ".envrc",
+    ".netrc",
+    ".npmrc",
+    ".pypirc",
+    ".aws/",
+    ".gnupg/",
+    ".ssh/",
 ]
 
-OBRISIGNORE = ".obrisignore"
-
-
-def _read_obrisignore(sync_dir: Path) -> list[str]:
-    path = sync_dir / OBRISIGNORE
-    if not path.exists():
-        return []
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return []
-    return [line for line in lines if line.strip() and not line.strip().startswith("#")]
-
 
 class ExclusionMatcher:
     """Single matcher built once per sync pass, queried per file.
@@ -80,8 +88,6 @@ class ExclusionMatcher:
         self._sources: list[tuple[str, str]] = []
         for pat in DEFAULT_EXCLUDES:
             self._sources.append(("default", pat))
-        for pat in _read_obrisignore(self.sync_dir):
-            self._sources.append((OBRISIGNORE, pat))
         for pat in state_excludes or []:
             self._sources.append(("state", pat))
         self._spec = pathspec.PathSpec.from_lines(GitWildMatchPattern, [pat for _, pat in self._sources])
@@ -94,8 +100,8 @@ class ExclusionMatcher:
         """Return ``[(source_label, pattern), ...]`` for every pattern that matches.
 
         A path can match multiple patterns; this returns all of them in
-        source order (defaults → .obrisignore → state). Used for
-        diagnostics, not for the actual exclude decision.
+        source order (defaults → state). Used for diagnostics, not
+        for the actual exclude decision.
         """
         matched = []
         for label, pat in self._sources:

{obris_cli-0.6.2 → obris_cli-0.7.0}/src/obris/sync/runner.py

@@ -115,7 +115,7 @@ def run_sync_pass(
                     "remote_updated_at": meta.get("remote_updated_at"),
                 }
             )
-    _emit_scan(scan, sync_dir, add_all_files, verbose=verbose)
+    _emit_scan(scan, sync_dir, add_all_files, dry_run=dry_run, verbose=verbose)
 
     if add_all_files and scan.untracked and not dry_run:
         # All targets share the same sync_dir; bulk-add against the
@@ -141,14 +141,29 @@ def run_sync_pass(
     return totals
 
 
-def _emit_scan(scan, sync_dir, add_all_files, *, verbose=False):
+def _emit_scan(scan, sync_dir, add_all_files, *, dry_run=False, verbose=False):
     if not scan.untracked and not scan.symlinks and not (verbose and scan.excluded):
         return
     cap = None if verbose else _LIST_PREVIEW
     if scan.untracked:
-        click.echo(f"\n{len(scan.untracked)} untracked file(s) in {sync_dir}/:")
-        _print_capped(scan.untracked, cap)
-        if not add_all_files:
+        # Output is shaped by the (dry_run, add_all_files) combination so
+        # the user always knows whether the listed files would actually
+        # be uploaded:
+        #   dry-run + --add-all  → preview header ("Would add ...")
+        #   dry-run, no --add-all → preview header ("would not add")
+        #   live    + --add-all  → silent here (the real add path prints
+        #                          its own "Added N file(s)" summary)
+        #   live, no --add-all   → the existing "Choose how to proceed"
+        #                          prompt with the add/skip recipes.
+        if dry_run and add_all_files:
+            click.echo(f"\nWould add {len(scan.untracked)} file(s):")
+            _print_capped(scan.untracked, cap)
+        elif dry_run:
+            click.echo(f"\n{len(scan.untracked)} untracked file(s) (would not add — re-run with --add-all):")
+            _print_capped(scan.untracked, cap)
+        elif not add_all_files:
+            click.echo(f"\n{len(scan.untracked)} untracked file(s) in {sync_dir}/:")
+            _print_capped(scan.untracked, cap)
             click.echo("  Choose how to proceed:")
             click.echo("    Upload all:   obris sync --add-all")
             click.echo("    Upload some:  obris sync add <file>...")

{obris_cli-0.6.2 → obris_cli-0.7.0}/src/obris/sync/state.py

@@ -1,8 +1,14 @@
 """Sync state persistence and manipulation.
 
-State is stored under ~/.obris/sync/, one file per (root topic, local path).
-State is keyed by knowledge_id (the remote item's primary key), not by
-filename. Renames on either side are metadata updates, not create+delete.
+State is stored in-place: ``<sync_dir>/.obris/<topic_id>.json``, one
+file per root topic. When the user deletes the sync dir, state goes
+with it — clean lifecycle, no orphaned global state, no cross-machine
+collisions when two laptops happen to share a path. Mirrors git's
+``.git/`` pattern.
+
+State is keyed by knowledge_id (the remote item's primary key), not
+by filename. Renames on either side are metadata updates, not
+create+delete.
 
 Subtopic support: one state file per *root* topic covers the entire
 subtree. topic_dirs maps topic_id -> relative directory (POSIX-style)
@@ -10,26 +16,39 @@ under local_path. The CLI only syncs root topics (parent_id = NULL);
 child topics are not valid sync targets on their own.
 """
 
-import hashlib
 import json
 from pathlib import Path
 
-from obris.config import CONFIG_DIR
-
 from .mapping import now_iso
 from .models import TrackedItem
 
-SYNC_DIR = CONFIG_DIR / "sync"
+# In-dir state directory name. Excluded by ``DEFAULT_EXCLUDES`` so the
+# engine never tries to sync state files as knowledge.
+STATE_DIR_NAME = ".obris"
+
+
+def _state_dir(local_path) -> Path:
+    return Path(local_path).resolve() / STATE_DIR_NAME
+
 
+def _state_path(topic_id, local_path) -> Path:
+    return _state_dir(local_path) / f"{topic_id}.json"
 
-def _state_key(topic_id, local_path):
-    """Deterministic short hash for a (topic_id, local_path) pair."""
-    raw = f"{topic_id}:{Path(local_path).resolve()}"
-    return hashlib.sha256(raw.encode()).hexdigest()[:16]
 
+def _ensure_state_dir(local_path) -> Path:
+    """Create ``<sync_dir>/.obris/`` and seed a self-excluding ``.gitignore``.
 
-def _state_path(topic_id, local_path):
-    return SYNC_DIR / f"{_state_key(topic_id, local_path)}.json"
+    The ``*`` line keeps the state dir out of git/svn checkouts of
+    the user's project — same trick git uses for ``.git/info``.
+    Idempotent: ``mkdir(parents=True, exist_ok=True)`` and we only
+    write the gitignore when missing.
+    """
+    state_dir = _state_dir(local_path)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    gitignore = state_dir / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*\n")
+    return state_dir
 
 
 def _read(path):
@@ -74,21 +93,24 @@ class SyncState:
     def find_all_for_path(cls, local_path):
         """Find all states for the given local path.
 
-        Returns list of (SyncState, topic_id) tuples.
+        Walks ``<local_path>/.obris/*.json``. Returns ``[]`` when the
+        state dir doesn't exist yet (fresh, never-synced directory).
         """
-        resolved = str(Path(local_path).resolve())
-        if not SYNC_DIR.exists():
+        resolved = Path(local_path).resolve()
+        state_dir = resolved / STATE_DIR_NAME
+        if not state_dir.exists():
             return []
         results = []
-        for f in SYNC_DIR.glob("*.json"):
+        for f in sorted(state_dir.glob("*.json")):
             data = _read(f)
-            if data and data.get("local_path") == resolved:
-                topic_id = data.get("topic_id")
-                results.append((cls(topic_id, local_path, data), topic_id))
+            if not data:
+                continue
+            topic_id = data.get("topic_id") or f.stem
+            results.append((cls(topic_id, local_path, data), topic_id))
         return results
 
     def save(self):
-        SYNC_DIR.mkdir(parents=True, exist_ok=True)
+        _ensure_state_dir(self.local_path)
         path = _state_path(self.topic_id, self.local_path)
         tmp = path.with_suffix(".tmp")
         data = {

{obris_cli-0.6.2 → obris_cli-0.7.0}/uv.lock

@@ -141,7 +141,7 @@ wheels = [
 
 [[package]]
 name = "obris-cli"
-version = "0.6.2"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

obris_cli-0.6.2/src/obris/commands/sync_config.py

@@ -1,178 +0,0 @@
-"""Per-checkout sync configuration subcommands.
-
-Hosts ``exclude`` / ``include`` / ``untrack`` — commands that modify
-state-file metadata for a synced directory. Kept out of
-``commands.sync`` so the sync group definition + invocation logic
-stays under the 300-line cap and these subcommands stay together
-because they share the ``_states_for_current_dir`` resolver.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import click
-
-from obris.sync.state import SyncState
-
-
-def _states_for_current_dir(path):
-    """Return ``(sync_dir, states)`` for ``path``, exiting cleanly if unsynced."""
-    sync_dir = Path(path).resolve()
-    states = SyncState.find_all_for_path(sync_dir)
-    if not states:
-        raise SystemExit(f"No synced topic found for {sync_dir}/. Run 'obris sync --topic <id>' first.")
-    return sync_dir, states
-
-
-def register(sync):
-    """Attach the config subcommands to the given Click group."""
-
-    @sync.command("exclude")
-    @click.argument("patterns", nargs=-1)
-    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
-    @click.option("--list", "list_only", is_flag=True, help="Print current exclude patterns and exit")
-    def sync_exclude(patterns, path, list_only):
-        """Add file patterns to skip during sync.
-
-        Patterns use gitignore-style syntax. Examples:
-
-        \b
-          obris sync exclude '*.draft.md'      # any markdown draft
-          obris sync exclude scratch/          # entire directory
-          obris sync exclude notes/private.md  # specific file
-          obris sync exclude --list            # show current patterns
-
-        Patterns apply to all topics syncing this directory. Idempotent —
-        adding a pattern twice is a no-op. Remove patterns with
-        'obris sync include <pattern>'.
-        """
-        sync_dir, states = _states_for_current_dir(path)
-
-        if list_only:
-            if patterns:
-                raise click.UsageError("Cannot combine --list with patterns.")
-            for state, tid in states:
-                current = state.exclude_patterns
-                header = f"Excludes for {tid}:" if len(states) > 1 else "Current excludes:"
-                click.echo(header)
-                if not current:
-                    click.echo("  (none)")
-                else:
-                    for p in current:
-                        click.echo(f"  {p}")
-            return
-
-        if not patterns:
-            raise click.UsageError("Provide one or more patterns, or use --list.")
-
-        added_total = []
-        for state, _tid in states:
-            added = state.add_excludes(patterns)
-            if added:
-                state.save()
-                added_total.extend(added)
-
-        unique_added = sorted(set(added_total))
-        skipped = sorted(set(patterns) - set(unique_added))
-        if unique_added:
-            click.echo(f"Added {len(unique_added)} pattern(s): {', '.join(unique_added)}")
-            click.echo(f"  Excludes apply on next 'obris sync' in {sync_dir}/.")
-        if skipped:
-            click.echo(f"Already present: {', '.join(skipped)}")
-
-    @sync.command("include")
-    @click.argument("patterns", nargs=-1, required=True)
-    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
-    def sync_include(patterns, path):
-        """Remove file patterns from the exclude list (re-enable syncing).
-
-        Inverse of 'obris sync exclude'. Idempotent — removing a pattern
-        that isn't present is a no-op with a notice.
-
-          obris sync include '*.draft.md'
-        """
-        sync_dir, states = _states_for_current_dir(path)
-
-        removed_total = []
-        for state, _tid in states:
-            removed = state.remove_excludes(patterns)
-            if removed:
-                state.save()
-                removed_total.extend(removed)
-
-        unique_removed = sorted(set(removed_total))
-        not_present = sorted(set(patterns) - set(unique_removed))
-        if unique_removed:
-            click.echo(f"Removed {len(unique_removed)} pattern(s): {', '.join(unique_removed)}")
-            click.echo(f"  Will sync on next 'obris sync' in {sync_dir}/.")
-        if not_present:
-            click.echo(f"Not in exclude list: {', '.join(not_present)}")
-
-    @sync.command("untrack")
-    @click.argument("targets", nargs=-1, required=True)
-    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
-    def sync_untrack(targets, path):
-        """Stop syncing items without deleting either side.
-
-        Each TARGET is a knowledge ID or a tracked filename (basename).
-        Removes the sync link; both the local file and the remote item stay
-        in place. Subsequent 'obris sync' calls will not re-pull these items.
-
-        \b
-          obris sync untrack abc123
-          obris sync untrack notes.md draft.md
-
-        Re-link later with 'obris sync link <file> -i <id>' or 'obris sync add'.
-        Permanently delete the remote with 'obris knowledge delete <id>'.
-        """
-        sync_dir, states = _states_for_current_dir(path)
-
-        untracked = []
-        not_found = []
-        for target in targets:
-            matches = _resolve_target(target, states)
-            if not matches:
-                not_found.append(target)
-                continue
-            if len(matches) > 1:
-                click.echo(f"Ambiguous: '{target}' matches multiple tracked items:")
-                for state, kid in matches:
-                    entry = state.get(kid)
-                    click.echo(f"  {kid}  ({entry.filename})")
-                click.echo("  Re-run with the specific knowledge ID.")
-                raise SystemExit(1)
-            state, kid = matches[0]
-            entry = state.get(kid)
-            state.untrack(kid)
-            state.mark_unlinked(kid)
-            state.save()
-            untracked.append((kid, entry.filename))
-
-        if untracked:
-            click.echo(f"Untracked {len(untracked)} item(s):")
-            for kid, name in untracked:
-                click.echo(f"  {name}  ({kid})")
-            click.echo(f"  Local files and remote items unchanged in {sync_dir}/.")
-        if not_found:
-            click.echo(f"Not tracked: {', '.join(not_found)}", err=True)
-            raise SystemExit(1)
-
-
-def _resolve_target(target, states):
-    """Resolve ``target`` (kid or filename) to a list of (state, kid) matches.
-
-    Filename lookup is by basename only (matches TrackedItem.filename).
-    Returns a list because the same filename can exist under different
-    topics in the same dir; the caller decides whether to error on
-    ambiguity.
-    """
-    matches = []
-    for state, _tid in states:
-        if state.is_tracked(target):
-            matches.append((state, target))
-            continue
-        kid, _entry = state.find_by_filename(target)
-        if kid:
-            matches.append((state, kid))
-    return matches