docs: add @example blocks to Python type stubs

[chaliy]

Context

Node's TypeScript wrapper (wrapper.ts) has JSDoc @example blocks on all public methods, providing inline usage examples that appear in IDE tooltips. Python's type stubs (crates/bashkit-python/bashkit/_bashkit.pyi) have type annotations but most methods lack usage examples in docstrings.

This is part of the Python ↔ Node binding parity effort (Phase 4 — Documentation Alignment).

What to implement

Add docstrings with Example: blocks to all public methods in crates/bashkit-python/bashkit/_bashkit.pyi.

Methods needing examples

Bash class:

class Bash:
    def __init__(self, ...):
        """Create a new Bash interpreter.
        
        Example::
        
            bash = Bash(username="dev", max_commands=1000)
            result = bash.execute_sync("echo hello")
            print(result.stdout)  # "hello\n"
        """

    async def execute(self, commands: str) -> ExecResult:
        """Execute bash commands asynchronously.
        
        Example::
        
            result = await bash.execute("echo hello && echo world")
            print(result.stdout)
        """

    def execute_sync(self, commands: str) -> ExecResult:
        """Execute bash commands synchronously.
        
        Example::
        
            result = bash.execute_sync("ls /tmp")
            print(result.exit_code)  # 0
        """
    
    # ... etc for all methods: execute_or_throw, execute_sync_or_throw,
    # cancel, reset, fs, mount, unmount, snapshot, restore_snapshot,
    # from_snapshot, read_file, write_file, ... (all convenience methods from #1257)

BashTool class:

class BashTool:
    def description(self) -> str:
        """Get the tool description for LLM consumption.
        
        Example::
        
            tool = BashTool()
            print(tool.description())  # Returns markdown description
        """
    # ... etc for all metadata methods

ScriptedTool class:

class ScriptedTool:
    def add_tool(self, name: str, description: str, callback: Callable, schema: dict | None = None):
        """Register a tool callable as a bash builtin.
        
        Example::
        
            def greet(params, stdin):
                return f"Hello, {params.get('name', 'world')}!"
            
            st = ScriptedTool(name="my-tool")
            st.add_tool("greet", "Greet someone", greet, {"name": {"type": "string"}})
        """

FileSystem class:

class FileSystem:
    def read_file(self, path: str) -> bytes:
        """Read a file from the virtual filesystem.
        
        Example::
        
            fs = bash.fs()
            content = fs.read_file("/tmp/data.txt")
            print(content.decode())
        """

ExecResult class:

class ExecResult:
    def to_dict(self) -> dict[str, Any]:
        """Convert result to a dictionary.
        
        Example::
        
            result = bash.execute_sync("echo hi")
            d = result.to_dict()
            print(d["stdout"])  # "hi\n"
            print(d["exit_code"])  # 0
        """

Also update module docstrings

bashkit/__init__.py — ensure module docstring has a complete quick-start example showing both sync and async usage.

bashkit/langchain.py, bashkit/pydantic_ai.py, bashkit/deepagents.py — ensure each module has a usage example in its docstring.

Acceptance criteria

• Every public method in _bashkit.pyi has a docstring with Example:: block
• Examples use reStructuredText :: block format (standard for Python docstrings)
• Examples are syntactically correct Python
• Examples match actual API behavior (not aspirational)
• Module docstrings in __init__.py, langchain.py, pydantic_ai.py, deepagents.py include usage examples
• ruff check passes
• mypy passes (if configured)
• IDE tooltip test: opening Python file that imports bashkit.Bash shows examples in hover