familiar-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{familiar_cli-0.4.0/src/familiar_cli.egg-info → familiar_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "familiar-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "compose and invoke ai agent prompts from reusable templates"
 readme = "readme.md"
 license = "MIT"

familiar_cli-0.5.0/src/familiar/_plugins.py

@@ -0,0 +1,44 @@
+"""Shared plugin loading utilities."""
+
+from __future__ import annotations
+
+import warnings
+from importlib.metadata import entry_points
+from typing import Any, Callable
+
+
+def load_plugins(
+    group: str,
+    validate: Callable[[Any], bool],
+    *,
+    label: str,
+    invalid_msg: str = "validation failed",
+) -> list[Any]:
+    """Load plugins from entry points with validation.
+
+    Args:
+        group: Entry point group name.
+        validate: Predicate that returns True for valid loaded objects.
+        label: Human-readable label for warning messages (e.g. "linter plugin").
+        invalid_msg: Message when validation fails.
+
+    Returns:
+        List of loaded and validated plugin objects.
+    """
+    results: list[Any] = []
+    for ep in entry_points(group=group):
+        try:
+            obj = ep.load()
+            if not validate(obj):
+                warnings.warn(
+                    f"{label} '{ep.name}': {invalid_msg}",
+                    stacklevel=2,
+                )
+                continue
+            results.append(obj)
+        except Exception as e:
+            warnings.warn(
+                f"failed to load {label} '{ep.name}': {e}",
+                stacklevel=2,
+            )
+    return results

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/src/familiar/agents.py

@@ -5,9 +5,10 @@ from __future__ import annotations
 import subprocess
 import warnings
 from abc import ABC, abstractmethod
-from importlib.metadata import entry_points
 from pathlib import Path
 
+from ._plugins import load_plugins
+
 
 class Agent(ABC):
     """Base class for AI coding agents."""
@@ -96,26 +97,22 @@ def load_agents() -> dict[str, Agent]:
         Dictionary mapping agent names to Agent instances.
         Plugins that fail to load are skipped with a warning.
     """
+    plugins = load_plugins(
+        "familiar.agents",
+        lambda cls: isinstance(cls, type) and issubclass(cls, Agent),
+        label="agent plugin",
+        invalid_msg="not a valid Agent subclass",
+    )
     agents: dict[str, Agent] = {}
-    eps = entry_points(group="familiar.agents")
-
-    for ep in eps:
+    for cls in plugins:
         try:
-            cls = ep.load()
-            if not (isinstance(cls, type) and issubclass(cls, Agent)):
-                warnings.warn(
-                    f"agent plugin '{ep.name}': not a valid Agent subclass",
-                    stacklevel=2,
-                )
-                continue
             instance = cls()
             agents[instance.name] = instance
         except Exception as e:
             warnings.warn(
-                f"failed to load agent plugin '{ep.name}': {e}",
+                f"failed to load agent plugin '{cls.__name__}': {e}",
                 stacklevel=2,
             )
-
     return agents
 
 

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/src/familiar/cli.py

@@ -10,6 +10,8 @@ import subprocess
 import sys
 import tempfile
 import traceback
+import warnings
+from importlib.metadata import version
 from pathlib import Path
 
 from .agents import get_agents, get_agent
@@ -26,8 +28,7 @@ from .render import (
 EXIT_SUCCESS = 0
 EXIT_ERROR = 1  # general error (agent failed, etc.)
 EXIT_USAGE = 2  # usage error (bad args, missing files, etc.)
-_VALID_SKILL_NAME = re.compile(r"^[a-z0-9_-]+$")
-_VALID_SUBAGENT_NAME = re.compile(r"^[a-z0-9_-]+$")
+_VALID_NAME = re.compile(r"^[a-z0-9_-]+$")
 
 
 class CliError(Exception):
@@ -41,6 +42,11 @@ class CliError(Exception):
         self.exit_code = exit_code
 
 
+def _agent_hint() -> str:
+    """Return a hint string listing valid agent names."""
+    return f"valid agents: {', '.join(get_agents().keys())}"
+
+
 def find_repo_root(start: Path) -> Path:
     """Find the repository root by looking for .git directory.
 
@@ -54,6 +60,25 @@ def find_repo_root(start: Path) -> Path:
     return cur
 
 
+def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
+    """Best-effort removal of a git worktree."""
+    try:
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                str(repo_root),
+                "worktree",
+                "remove",
+                "--force",
+                str(worktree_path),
+            ],
+            capture_output=True,
+        )
+    except FileNotFoundError:
+        pass
+
+
 def create_worktree(repo_root: Path) -> Path:
     """Create a temporary git worktree for the repository."""
     # Ensure it's a git repo
@@ -98,7 +123,7 @@ def write_instruction(repo_root: Path, agent_name: str, system: str) -> None:
     try:
         agent = get_agent(agent_name)
     except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+        raise CliError(str(e), hint=_agent_hint())
     (repo_root / agent.output_file).write_text(system.strip() + "\n", encoding="utf-8")
 
 
@@ -106,7 +131,7 @@ def write_skill(
     repo_root: Path, agent_name: str, invocation: str, skill_name: str, prompt: str
 ) -> Path:
     """Write a reusable skill file for supported agents."""
-    if not _VALID_SKILL_NAME.match(skill_name):
+    if not _VALID_NAME.match(skill_name):
         raise CliError(
             f"invalid skill name: {skill_name}",
             hint="use lowercase letters, numbers, underscore, or hyphen",
@@ -115,7 +140,7 @@ def write_skill(
     try:
         agent = get_agent(agent_name)
     except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+        raise CliError(str(e), hint=_agent_hint())
 
     if not agent.supports_skills():
         raise CliError(f"agent does not support skills: {agent_name}")
@@ -143,7 +168,7 @@ def write_subagent(
     system: str,
 ) -> Path:
     """Write a reusable subagent file for supported agents."""
-    if not _VALID_SUBAGENT_NAME.match(subagent_name):
+    if not _VALID_NAME.match(subagent_name):
         raise CliError(
             f"invalid subagent name: {subagent_name}",
             hint="use lowercase letters, numbers, underscore, or hyphen",
@@ -152,7 +177,7 @@ def write_subagent(
     try:
         agent = get_agent(agent_name)
     except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+        raise CliError(str(e), hint=_agent_hint())
 
     if not agent.supports_subagents():
         raise CliError(f"agent does not support subagents: {agent_name}")
@@ -192,7 +217,7 @@ def run_agent(
     try:
         agent = get_agent(agent_name)
     except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+        raise CliError(str(e), hint=_agent_hint())
     try:
         return agent.run(repo_root, prompt, headless, auto=auto)
     except FileNotFoundError:
@@ -258,8 +283,11 @@ def cmd_invoke(args: argparse.Namespace) -> int:
             instr_file = repo_root / agent.output_file
             if instr_file.exists():
                 shutil.copy2(instr_file, target_dir / agent.output_file)
-        except (OSError, KeyError):
-            pass
+        except (OSError, KeyError) as exc:
+            warnings.warn(
+                f"failed to copy instruction file into worktree: {exc}",
+                stacklevel=2,
+            )
 
     try:
         rc = run_agent(
@@ -271,7 +299,7 @@ def cmd_invoke(args: argparse.Namespace) -> int:
         return rc
     except Exception:
         if args.worktree:
-            print(f"\nworktree remains at: {target_dir}")
+            _remove_worktree(repo_root, target_dir)
         raise
 
 
@@ -357,6 +385,11 @@ def main() -> None:
         "  familiar lint                        # validate prompts\n",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('familiar-cli')}",
+    )
     parser.add_argument(
         "--debug", action="store_true", help="show full traceback on error"
     )

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/src/familiar/lint.py

@@ -3,12 +3,12 @@
 from __future__ import annotations
 
 import re
-import warnings
 from dataclasses import dataclass
-from importlib.metadata import entry_points
 from pathlib import Path
 from typing import Callable, Literal
 
+from ._plugins import load_plugins
+
 from .render import _SNIPPET_INCLUDE, NotFoundError, list_items, load_snippet, load_text
 
 
@@ -202,27 +202,12 @@ def load_linters(kind: Literal["conjurings", "invocations"]) -> list[LinterFunc]
     Returns:
         List of linter functions from plugins.
     """
-    linters: list[LinterFunc] = []
-    group = f"familiar.linters.{kind}"
-    eps = entry_points(group=group)
-
-    for ep in eps:
-        try:
-            func = ep.load()
-            if not callable(func):
-                warnings.warn(
-                    f"linter plugin '{ep.name}': not callable",
-                    stacklevel=2,
-                )
-                continue
-            linters.append(func)
-        except Exception as e:
-            warnings.warn(
-                f"failed to load linter plugin '{ep.name}': {e}",
-                stacklevel=2,
-            )
-
-    return linters
+    return load_plugins(
+        f"familiar.linters.{kind}",
+        callable,
+        label="linter plugin",
+        invalid_msg="not callable",
+    )
 
 
 def lint_snippet_references(

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/src/familiar/render.py

@@ -118,71 +118,85 @@ def _walk_traversable(root: Traversable, prefix: str = "") -> list[tuple[str, st
     return items
 
 
-def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
-    """List available snippets.
-
-    Returns list of (path, first_line, is_local) tuples, sorted by path.
+def _list_resources(
+    repo_root: Path,
+    pkg: str,
+    local_subdir: str,
+    *,
+    recursive: bool = False,
+    suffix: str = "",
+) -> list[tuple[str, str, bool]]:
+    """List resources from package data and local overrides.
+
+    Items from local ``.familiar/{local_subdir}/`` override package builtins.
+
+    Args:
+        repo_root: Repository root path.
+        pkg: Package name to scan for builtins.
+        local_subdir: Subdirectory name under ``.familiar/`` for local overrides.
+        recursive: If True, scan recursively (for nested resources like snippets).
+        suffix: File suffix filter (e.g. ``".md"``). Empty string matches all files.
+
+    Returns:
+        Sorted list of ``(key, first_line, is_local)`` tuples.
     """
     items: dict[str, tuple[str, bool]] = {}
 
-    # built-ins
+    # built-in resources from package data
     try:
-        pkg_root = resources.files("familiar.data.snippets")
-        for rel, first_line in _walk_traversable(pkg_root):
-            items[rel] = (first_line, False)
+        pkg_root = resources.files(pkg)
+        if recursive:
+            for rel, first_line in _walk_traversable(pkg_root):
+                items[rel] = (first_line, False)
+        else:
+            for item in pkg_root.iterdir():
+                if suffix and not item.name.endswith(suffix):
+                    continue
+                if item.name.startswith("_"):
+                    continue
+                key = item.name[: -len(suffix)] if suffix else item.name
+                content = item.read_text(encoding="utf-8")
+                first_line = content.split("\n", 1)[0].strip()
+                items[key] = (first_line, False)
     except (FileNotFoundError, TypeError, ModuleNotFoundError):
         pass
 
     # local overrides
-    local_dir = repo_root / ".familiar" / "snippets"
+    local_dir = repo_root / ".familiar" / local_subdir
     if local_dir.is_dir():
-        for f in sorted(local_dir.rglob("*")):
-            if f.is_file() and not f.name.startswith("_"):
-                rel = str(f.relative_to(local_dir))
-                content = f.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[rel] = (first_line, True)
+        files = (
+            sorted(local_dir.rglob("*")) if recursive else local_dir.glob(f"*{suffix}")
+        )
+        for f in files:
+            if not f.is_file() or f.name.startswith("_"):
+                continue
+            key = str(f.relative_to(local_dir)) if recursive else f.stem
+            content = f.read_text(encoding="utf-8")
+            first_line = content.split("\n", 1)[0].strip()
+            items[key] = (first_line, True)
 
     return [
-        (path, first_line, is_local)
-        for path, (first_line, is_local) in sorted(items.items())
+        (key, first_line, is_local)
+        for key, (first_line, is_local) in sorted(items.items())
     ]
 
 
-def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
-    """List available conjurings or invocations.
+def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
+    """List available snippets.
 
-    Returns list of (name, first_line, is_local) tuples, sorted by name.
+    Returns list of (path, first_line, is_local) tuples, sorted by path.
     """
-    items: dict[str, tuple[str, bool]] = {}
+    return _list_resources(
+        repo_root, "familiar.data.snippets", "snippets", recursive=True
+    )
 
-    # built-ins
-    pkg = f"familiar.data.{kind}"
-    try:
-        pkg_files = resources.files(pkg)
-        for item in pkg_files.iterdir():
-            if item.name.endswith(".md") and not item.name.startswith("_"):
-                name = item.name[:-3]
-                content = item.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[name] = (first_line, False)
-    except (FileNotFoundError, TypeError):
-        pass
 
-    # local overrides
-    local_dir = repo_root / ".familiar" / kind
-    if local_dir.is_dir():
-        for f in local_dir.glob("*.md"):
-            if not f.name.startswith("_"):
-                name = f.stem
-                content = f.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[name] = (first_line, True)
+def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
+    """List available conjurings or invocations.
 
-    return [
-        (name, first_line, is_local)
-        for name, (first_line, is_local) in sorted(items.items())
-    ]
+    Returns list of (name, first_line, is_local) tuples, sorted by name.
+    """
+    return _list_resources(repo_root, f"familiar.data.{kind}", kind, suffix=".md")
 
 
 def compose_system(repo_root: Path, conjurings: list[str]) -> str:

{familiar_cli-0.4.0 → familiar_cli-0.5.0/src/familiar_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/src/familiar_cli.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 pyproject.toml
 readme.md
 src/familiar/__init__.py
+src/familiar/_plugins.py
 src/familiar/agents.py
 src/familiar/cli.py
 src/familiar/lint.py

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/tests/test_agents.py

@@ -68,7 +68,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "invalid"
         mock_ep.load.return_value = str  # not an Agent subclass
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="not a valid Agent subclass"):
                 agents = load_agents()
             assert "invalid" not in agents
@@ -79,7 +79,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "broken"
         mock_ep.load.side_effect = ImportError("module not found")
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 agents = load_agents()
             assert "broken" not in agents
@@ -101,7 +101,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "bad"
         mock_ep.load.return_value = BadAgent
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 agents = load_agents()
             assert "bad" not in agents

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/tests/test_cli.py

@@ -13,6 +13,7 @@ from familiar.cli import (
     write_instruction,
     parse_kv,
     run_agent,
+    main,
     cmd_conjure,
     cmd_invoke,
     cmd_list,
@@ -21,6 +22,19 @@ from familiar.cli import (
 )
 
 
+class TestVersion:
+    """tests for --version flag."""
+
+    def test_version_prints_and_exits(self, capsys):
+        with pytest.raises(SystemExit, match="0"):
+            with patch("sys.argv", ["familiar", "--version"]):
+                main()
+        captured = capsys.readouterr()
+        assert "familiar" in captured.out
+        # version string should look like a semver
+        assert any(c.isdigit() for c in captured.out)
+
+
 class TestCreateWorktree:
     """tests for git worktree creation."""
 
@@ -329,6 +343,27 @@ class TestCmdInvoke:
                     # Check that instruction file was copied
                     mock_copy.assert_called_once()
 
+    def test_invoke_worktree_cleaned_up_on_error(self, tmp_path):
+        with patch("familiar.cli.create_worktree", return_value=tmp_path / "wt"):
+            with patch("familiar.cli.run_agent", side_effect=RuntimeError("boom")):
+                with patch("familiar.cli._remove_worktree") as mock_remove:
+                    args = argparse.Namespace(
+                        agent="claude",
+                        invocation="explain",
+                        into=str(tmp_path),
+                        headless=True,
+                        auto=False,
+                        dry_run=False,
+                        kv=None,
+                        inv_args=[],
+                        worktree=True,
+                        save_skill=False,
+                        skill_name=None,
+                    )
+                    with pytest.raises(RuntimeError, match="boom"):
+                        cmd_invoke(args)
+                    mock_remove.assert_called_once()
+
     def test_invoke_save_skill_claude(self, tmp_path):
         with patch("familiar.cli.run_agent") as mock_run:
             args = argparse.Namespace(

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/tests/test_lint.py

@@ -225,7 +225,7 @@ class TestLinterPlugins:
         mock_ep.name = "invalid"
         mock_ep.load.return_value = "not a function"
 
-        with patch("familiar.lint.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="not callable"):
                 linters = load_linters("conjurings")
             assert len(linters) == 0
@@ -236,7 +236,7 @@ class TestLinterPlugins:
         mock_ep.name = "broken"
         mock_ep.load.side_effect = ImportError("module not found")
 
-        with patch("familiar.lint.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 linters = load_linters("conjurings")
             assert len(linters) == 0
@@ -258,7 +258,7 @@ class TestLinterPlugins:
         templates.mkdir(parents=True)
         (templates / "mytemplate.md").write_text("# test")
 
-        with patch("familiar.lint.entry_points") as mock_entry_points:
+        with patch("familiar._plugins.entry_points") as mock_entry_points:
             # Return our mock for templates, empty for invocations
             def ep_side_effect(group):
                 if group == "familiar.linters.conjurings":
@@ -287,7 +287,7 @@ class TestLinterPlugins:
         templates.mkdir(parents=True)
         (templates / "test.md").write_text("# test")
 
-        with patch("familiar.lint.entry_points") as mock_entry_points:
+        with patch("familiar._plugins.entry_points") as mock_entry_points:
 
             def ep_side_effect(group):
                 if group == "familiar.linters.conjurings":

{familiar_cli-0.4.0 → familiar_cli-0.5.0}/tests/test_render.py

@@ -121,6 +121,34 @@ class TestComposeSystem:
         # verify order: core, then conjurings in order
         assert system == "CORE\n\nFIRST\n\nSECOND"
 
+    def test_compose_core_only(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("CORE")
+
+        system = compose_system(tmp_path, [])
+        assert system == "CORE"
+
+    def test_compose_multiple_conjurings(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("CORE")
+        (templates / "a.md").write_text("A")
+        (templates / "b.md").write_text("B")
+        (templates / "c.md").write_text("C")
+
+        system = compose_system(tmp_path, ["a", "b", "c"])
+        assert system == "CORE\n\nA\n\nB\n\nC"
+
+    def test_compose_strips_whitespace(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("  CORE  \n")
+        (templates / "pad.md").write_text("\n  PAD  \n\n")
+
+        system = compose_system(tmp_path, ["pad"])
+        assert system == "CORE\n\nPAD"
+
     def test_compose_missing_profile_raises(self, tmp_path):
         with pytest.raises(NotFoundError, match="unknown conjuring"):
             compose_system(tmp_path, ["nonexistent"])
@@ -137,6 +165,36 @@ class TestRenderInvocation:
         result = render_invocation(tmp_path, "greet", ["world"], {"style": "friendly"})
         assert result == "hello world, friendly"
 
+    def test_render_with_snippet_and_args(self, tmp_path):
+        snippets = tmp_path / ".familiar" / "snippets" / "test"
+        snippets.mkdir(parents=True)
+        (snippets / "header.txt").write_text("== $1 ==")
+
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "demo.md").write_text(
+            "{{> snippet:test/header.txt}}\nbody: {{mode}}"
+        )
+
+        result = render_invocation(tmp_path, "demo", ["title"], {"mode": "fast"})
+        assert result == "== title ==\nbody: fast"
+
+    def test_render_no_args(self, tmp_path):
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "plain.md").write_text("no placeholders here")
+
+        result = render_invocation(tmp_path, "plain", [], {})
+        assert result == "no placeholders here"
+
+    def test_render_arguments_placeholder(self, tmp_path):
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "all.md").write_text("run $ARGUMENTS")
+
+        result = render_invocation(tmp_path, "all", ["a", "b", "c"], {})
+        assert result == "run a b c"
+
     def test_render_missing_invocation_raises(self, tmp_path):
         with pytest.raises(NotFoundError, match="unknown invocation"):
             render_invocation(tmp_path, "nonexistent", [], {})
@@ -259,6 +317,15 @@ class TestResolveIncludes:
         with pytest.raises(NotFoundError, match="unknown snippet"):
             resolve_includes(tmp_path, text)
 
+    def test_nonexistent_among_valid_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "good.txt").write_text("ok")
+
+        text = "{{> snippet:test/good.txt}} {{> snippet:test/missing.txt}}"
+        with pytest.raises(NotFoundError, match="unknown snippet"):
+            resolve_includes(tmp_path, text)
+
     def test_include_before_substitute(self, tmp_path):
         """Include resolution happens before placeholder substitution."""
         snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
@@ -325,3 +392,25 @@ class TestListSnippets:
         _, first_line, is_local = custom_items[0]
         assert is_local is True
         assert first_line == "first line here"
+
+    def test_local_override_preserves_other_builtins(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "python"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "pyproject.toml").write_text("custom")
+
+        items = list_snippets(tmp_path)
+        lookup = {p: (f, loc) for p, f, loc in items}
+        assert lookup["python/pyproject.toml"][1] is True
+        assert "rust/Cargo.toml" in lookup
+        assert lookup["rust/Cargo.toml"][1] is False
+
+    def test_local_underscore_files_excluded(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "_hidden.txt").write_text("should not appear")
+        (snippet_dir / "visible.txt").write_text("should appear")
+
+        items = list_snippets(tmp_path)
+        paths = [p for p, _, _ in items]
+        assert "test/visible.txt" in paths
+        assert "test/_hidden.txt" not in paths