ayder-cli 0.99.90__tar.gz → 1.0__tar.gz

{ayder_cli-0.99.90 → ayder_cli-1.0}/AGENTS.md

@@ -10,8 +10,6 @@ This document provides coding standards, tool configurations, and workflows for
 - **Virtual Environment**: `.venv` (already configured)
 - **Project Structure**: Standard Python package in `src/ayder_cli/`
 
-> **📖 For detailed architecture notes, module relationships, and TUI structure, see [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md)**
-
 ## Tech Stack
 
 ### Core Dependencies
@@ -23,6 +21,7 @@ This document provides coding standards, tool configurations, and workflows for
 | **rich** | Rich text and beautiful formatting | >=13.0.0 |
 | **prompt-toolkit** | Interactive CLI prompts and auto-completion | latest |
 | **python-dotenv** | Environment variable management | >=1.0.0 |
+| **httpx** | Async HTTP client (Ollama API, fetch_web) | latest |
 
 ### Development Dependencies
 
@@ -50,10 +49,12 @@ This document provides coding standards, tool configurations, and workflows for
 ayder-cli/
 ├── src/ayder_cli/              # Main source code
 │   ├── cli.py                  # Entry point (argparse)
-│   ├── cli_runner.py           # Command execution logic
-│   ├── client.py               # ChatSession + Agent classes
+│   ├── cli_runner.py           # CLI command execution logic
+│   ├── cli_callbacks.py        # CLI callback implementations
+│   ├── client.py               # ChatSession helpers
 │   ├── console.py              # Rich console instance
 │   ├── version.py              # Version info
+│   ├── logging_config.py       # Loguru setup
 │   │
 │   ├── core/                   # Core infrastructure
 │   │   ├── config.py           # Pydantic config with validation
@@ -61,84 +62,93 @@ ayder-cli/
 │   │   └── result.py           # ToolSuccess/ToolError types
 │   │
 │   ├── application/            # Shared application layer (CLI + TUI)
-│   │   ├── checkpoint_orchestrator.py  # CheckpointOrchestrator, RuntimeContext
 │   │   ├── execution_policy.py         # ExecutionPolicy, PermissionDeniedError
 │   │   ├── message_contract.py         # LLM message format contracts
 │   │   ├── runtime_factory.py          # create_runtime() composition root
 │   │   ├── temporal_contract.py        # Temporal workflow contracts
 │   │   ├── temporal_metadata.py        # Temporal metadata types
-│   │   └── validation.py               # ValidationAuthority, SchemaValidator
+│   │   └── validation.py              # ValidationAuthority, SchemaValidator
 │   │
 │   ├── loops/                  # Shared agent loop base
 │   │   ├── base.py             # AgentLoopBase (iteration, checkpoint, routing)
 │   │   └── config.py           # Shared LoopConfig dataclass
 │   │
+│   ├── providers/              # LLM provider implementations
+│   │   ├── base.py             # AIProvider protocol, NormalizedStreamChunk
+│   │   ├── provider_orchestrator.py  # Factory: create(config) → provider
+│   │   └── impl/               # Individual provider drivers
+│   │       ├── openai.py       # OpenAIProvider (base for most drivers)
+│   │       ├── ollama.py       # OllamaProvider (native + XML fallback)
+│   │       ├── claude.py       # ClaudeProvider (Anthropic SDK)
+│   │       ├── gemini.py       # GeminiProvider (Google GenAI SDK)
+│   │       ├── deepseek.py     # DeepSeekProvider (OpenAI-compatible)
+│   │       ├── qwen.py         # QwenNativeProvider (DashScope SDK)
+│   │       └── glm.py          # GLMNativeProvider (ZhipuAI SDK)
+│   │
 │   ├── services/               # Service layer
-│   │   ├── llm.py              # OpenAI/Ollama LLM provider
 │   │   ├── interactions.py     # InteractionSink, ConfirmationPolicy protocols
 │   │   └── tools/
 │   │       └── executor.py     # ToolExecutor (CLI confirmation + diff preview)
 │   │
-│   ├── tools/                  # Tool framework + implementations (28 tools)
-│   │   ├── definition.py       # ToolDefinition base + auto-discovery
-│   │   ├── registry.py         # Tool registry with middleware
+│   ├── tools/                  # Tool framework + implementations (25 tools)
+│   │   ├── definition.py       # ToolDefinition dataclass + auto-discovery
+│   │   ├── registry.py         # ToolRegistry (schema, execution, system prompts)
 │   │   ├── schemas.py          # OpenAI-format JSON schemas
 │   │   ├── execution.py        # Tool execution engine
 │   │   ├── hooks.py            # Hook/middleware system
-│   │   ├── normalization.py    # Argument normalization
+│   │   ├── normalization.py    # Argument normalization + path resolution
 │   │   ├── utils.py            # Tool utilities
 │   │   └── builtins/           # Built-in tool implementations
-│   │       ├── *_definitions.py # Distributed tool definitions (12 files)
-│   │       ├── filesystem.py   # File system tools
-│   │       ├── python_editor.py # CST-based Python editor tool
-│   │       ├── search.py       # Search tools
-│   │       ├── shell.py        # Shell tools
-│   │       ├── venv.py         # Virtualenv tools
-│   │       ├── utils_tools.py  # Utility tools
-│   │       ├── web.py          # Web fetching tool
+│   │       ├── *_definitions.py # Distributed tool definitions (13 files)
+│   │       ├── filesystem.py   # file_explorer, read_file, file_editor
+│   │       ├── python_editor.py # CST-based Python structural editor
+│   │       ├── search.py       # search_codebase, get_project_structure
+│   │       ├── shell.py        # run_shell_command
+│   │       ├── venv.py         # Virtualenv management tools
+│   │       ├── utils_tools.py  # manage_environment_vars
+│   │       ├── web.py          # fetch_web
+│   │       ├── dbs_tool.py     # DBS RAG API tool
 │   │       └── temporal.py     # Temporal workflow tool
 │   │
 │   ├── tui/                    # Textual TUI (main interface)
+│   │   ├── __init__.py         # run_tui() entry point
 │   │   ├── app.py              # AyderApp main application
 │   │   ├── chat_loop.py        # TUI async chat loop (TuiChatLoop)
-│   │   ├── commands.py         # Slash command handlers
+│   │   ├── commands.py         # Slash command handlers (19 commands)
 │   │   ├── helpers.py          # TUI helper functions
-│   │   ├── parser.py           # XML tool call parser
-│   │   ├── screens.py          # Modal screens (confirm, select, etc.)
+│   │   ├── adapter.py          # TUIInteractionSink (verbose debug)
+│   │   ├── parser.py           # Message parsing
+│   │   ├── screens.py          # Modal screens (confirm, select, permission, task edit)
 │   │   ├── theme_manager.py    # Theme loading and CSS
-│   │   ├── types.py            # Shared types
-│   │   └── widgets.py          # ChatView, ToolPanel, etc.
+│   │   ├── types.py            # MessageType, ConfirmResult
+│   │   └── widgets.py          # ChatView, ToolPanel, CLIInputBar, StatusBar
 │   │
 │   ├── themes/                 # TUI themes
 │   │   ├── __init__.py         # Theme registry
 │   │   ├── claude.py           # Claude theme CSS
 │   │   └── original.py         # Original theme CSS
 │   │
-│   ├── chat_loop.py            # Sync CLI agent loop (ChatLoop)
-│   ├── checkpoint_manager.py   # Memory checkpoint/restore
 │   ├── memory.py               # Cross-session memory storage
 │   ├── notes.py                # Note management (.ayder/notes/)
-│   ├── parser.py               # XML tool call parser
+│   ├── parser.py               # XML/JSON tool call parser
 │   ├── process_manager.py      # Background process management
-│   ├── prompts.py              # System prompts templates
+│   ├── prompts.py              # System prompt templates
 │   ├── tasks.py                # Task management (.ayder/tasks/)
-│   └── ui.py                   # Rich terminal UI
+│   └── ui.py                   # Rich terminal UI helpers
 │
-├── tests/                      # Test suite
-│   ├── client/                 # Client tests
+├── tests/                      # Test suite (998+ tests)
+│   ├── application/            # Application layer tests
 │   ├── core/                   # Core tests
 │   ├── services/               # Services tests
 │   ├── tools/                  # Tool tests
 │   ├── ui/                     # TUI tests
 │   └── *.py                    # Top-level tests
 │
-├── docs/                       # Documentation
-├── .ayder/                     # Project-specific data (tasks, notes, memory)
+├── .ayder/                     # Project-specific data (tasks, notes, memory, skills)
 ├── pyproject.toml              # Project configuration
 ├── AGENTS.md                   # This file
-├── CLAUDE.md                   # Redirects to AGENTS.md and PROJECT_STRUCTURE.md
-├── GEMINI.md                   # Additional notes
-└── README.md                   # Project overview
+├── README.md                   # Project overview
+└── .claude/                    # Claude Code configuration + skills
 ```
 
 ### Key Files Reference
@@ -147,20 +157,18 @@ ayder-cli/
 |------|---------|
 | `cli.py` | Entry point, argument parsing |
 | `tui/app.py` | Main TUI application (AyderApp) |
-| `tui/commands.py` | Slash command handlers (/help, /model, etc.) |
+| `tui/commands.py` | Slash command handlers (19 commands) |
 | `tui/chat_loop.py` | Async LLM loop for TUI (TuiChatLoop + TuiCallbacks protocol) |
-| `chat_loop.py` | Sync CLI agent loop (ChatLoop) |
-| `client.py` | ChatSession, Agent, call_llm_async() |
+| `cli_runner.py` | CLI command execution + sync agent loop |
+| `application/runtime_factory.py` | `create_runtime()` — single composition root for CLI + TUI |
 | `application/execution_policy.py` | Shared permission + tool execution policy |
 | `application/validation.py` | ValidationAuthority + SchemaValidator (single validation path) |
-| `application/checkpoint_orchestrator.py` | CheckpointOrchestrator (shared checkpoint logic) |
-| `application/runtime_factory.py` | create_runtime() — single composition root |
-| `loops/base.py` | AgentLoopBase shared by ChatLoop and TuiChatLoop |
-| `tools/builtins/filesystem.py` | File system tool implementations |
-| `tools/builtins/python_editor.py` | CST-based Python structural editor |
-| `tools/builtins/search.py` | Search tool implementations |
+| `loops/base.py` | AgentLoopBase shared by CLI and TUI loops |
+| `tools/definition.py` | ToolDefinition dataclass + auto-discovery from `*_definitions.py` |
+| `tools/registry.py` | ToolRegistry: schemas, execution, system prompts, tag filtering |
 | `core/config.py` | Configuration with Pydantic validation |
 | `core/context.py` | ProjectContext for path sandboxing |
+| `providers/provider_orchestrator.py` | Factory dispatching to correct driver |
 
 ## Environment Setup
 
@@ -252,19 +260,10 @@ uv run mypy src/
 If neither poe nor uv run work, activate the venv manually:
 
 ```bash
-# Activate virtual environment
 source .venv/bin/activate
-
-# Run tests using python3 (not python)
 python3 -m pytest tests/ -x --timeout=30 --ignore=tests/ui/test_tui_chat_loop.py
-
-# Lint
 python3 -m ruff check src/
-
-# Type check
 python3 -m mypy src/
-
-# Deactivate when done
 deactivate
 ```
 
@@ -274,7 +273,7 @@ deactivate
 
 - **Line Length**: 88 characters (Black-compatible)
 - **Quotes**: Use double quotes for strings
-- **Imports**: Sort with `isort` style (standard lib → third-party → local)
+- **Imports**: Sort with `isort` style (standard lib > third-party > local)
 - **Type Hints**: Use Python 3.12+ syntax (`str | None` instead of `Optional[str]`)
 - **Docstrings**: Use Google-style docstrings
 
@@ -307,39 +306,14 @@ from ayder_cli.ui import console
 
 ## Linting with Ruff
 
-### Using poe (Recommended)
-
 ```bash
-# Check all source files
+# Using poe (Recommended)
 uv run poe lint
-
-# Check with auto-fix
 uv run poe lint-fix
-```
-
-### Using uv run (Fallback)
 
-```bash
-# Check all source files
+# Using uv run (Fallback)
 uv run ruff check src/
-
-# Check with auto-fix (safe fixes only)
 uv run ruff check src/ --fix
-
-# Check specific file
-uv run ruff check src/ayder_cli/cli_runner.py
-
-# Show all enabled rules
-uv run ruff linter
-```
-
-### Using manual venv (Last Resort)
-
-```bash
-source .venv/bin/activate
-python3 -m ruff check src/
-python3 -m ruff check src/ --fix
-deactivate
 ```
 
 ### Ruff Standards
@@ -356,31 +330,12 @@ uv run poe lint  # Must pass with no errors
 
 ## Type Checking with Mypy
 
-### Using poe (Recommended)
-
 ```bash
+# Using poe (Recommended)
 uv run poe typecheck
-```
-
-### Using uv run (Fallback)
 
-```bash
-# Check all source files
+# Using uv run (Fallback)
 uv run mypy src/
-
-# Check specific file
-uv run mypy src/ayder_cli/cli_runner.py
-
-# Check with detailed output
-uv run mypy src/ --show-error-codes
-```
-
-### Using manual venv (Last Resort)
-
-```bash
-source .venv/bin/activate
-python3 -m mypy src/
-deactivate
 ```
 
 ### Type Annotation Standards
@@ -389,70 +344,19 @@ deactivate
 # Use modern Union syntax
 def func(x: str | None) -> int: ...
 
-# Instead of old Optional syntax
-def func(x: Optional[str]) -> int: ...  # Don't use
-
 # Use built-in generics
 def process(items: list[str]) -> dict[str, int]: ...
-
-# Explicit None defaults require Optional
-def greet(name: str | None = None) -> str: ...
 ```
 
-**Note**: Mypy errors about `Optional` defaults are expected in some places due to historical code. New code should use proper `| None` annotations.
-
 ## Testing with pytest
 
-### Using poe (Recommended)
-
-```bash
-# Run tests (excludes slow TUI tests)
-uv run poe test
-
-# Run all tests including TUI
-uv run poe test-all
-
-# Run tests with verbose output
-uv run poe test-verbose
-```
-
-### Using uv run (Fallback)
-
-```bash
-# Run all tests
-uv run pytest tests/ -v
-
-# Run with coverage
-uv run pytest tests/ --cov=src/ayder_cli --cov-report=term-missing
-
-# Run specific test file
-uv run pytest tests/test_cli.py -v
-
-# Run specific test
-uv run pytest tests/test_cli.py::TestMainFunction -v
-
-# Run with timeout (recommended)
-uv run pytest tests/ -x --timeout=30
-
-# Run parallel (fastest)
-uv run pytest tests/ -n auto --timeout=30
-
-# Run excluding slow TUI tests
-uv run pytest tests/ --ignore=tests/ui/test_tui_chat_loop.py
-```
-
-### Using manual venv (Last Resort)
-
 ```bash
-source .venv/bin/activate
-
-# Run tests using python3 (not python)
-python3 -m pytest tests/ -x --timeout=30 --ignore=tests/ui/test_tui_chat_loop.py
-
-# Run with verbose output
-python3 -m pytest tests/ -v
-
-deactivate
+# Using poe (Recommended)
+uv run poe test          # Excludes slow TUI tests
+uv run poe test-all      # All tests including TUI
+uv run poe test-fast     # Parallel execution
+uv run poe test-verbose  # Verbose output
+uv run poe test-cov      # With coverage report
 ```
 
 ### Test Standards
@@ -474,12 +378,12 @@ from ayder_cli import some_module
 
 class TestFeature:
     """Test suite for feature."""
-    
+
     def test_basic_functionality(self):
         """Test normal operation."""
         result = some_module.function()
         assert result == expected
-    
+
     @patch("ayder_cli.module.subprocess.run")
     def test_with_mocking(self, mock_run):
         """Test with external dependencies mocked."""
@@ -488,106 +392,11 @@ class TestFeature:
         assert mock_run.called
 ```
 
-## Pre-Commit Checklist
-
-Before submitting changes, run:
-
-### Option 1: Using poe (RECOMMENDED)
-
-```bash
-cd /Users/sinanalyuruk/Vscode/ayder-cli
+## Architecture
 
-# Run all checks (lint + typecheck + test)
-# Note: typecheck may show pre-existing errors, but lint and test must pass
-uv run poe check-all
+### Runtime Factory
 
-# Or run individually:
-uv run poe lint      # Must pass
-uv run poe test      # Must pass
-uv run poe typecheck # Review errors (pre-existing issues exist)
-```
-
-### Option 2: Using uv run (Fallback)
-
-```bash
-cd /Users/sinanalyuruk/Vscode/ayder-cli
-
-# 1. Linting (must pass)
-uv run ruff check src/ tests/
-
-# 2. Type checking (review errors)
-uv run mypy src/
-
-# 3. Tests (must pass)
-uv run pytest tests/ -x --timeout=30 --ignore=tests/ui/test_tui_chat_loop.py
-
-# 4. All checks in one go
-uv run ruff check src/ tests/ && echo "✅ Ruff passed" || echo "❌ Ruff failed"
-uv run pytest tests/ -x --timeout=30 --ignore=tests/ui/test_tui_chat_loop.py -q && echo "✅ Tests passed" || echo "❌ Tests failed"
-```
-
-### Option 3: Manual venv (Last Resort)
-
-```bash
-cd /Users/sinanalyuruk/Vscode/ayder-cli
-source .venv/bin/activate
-
-# 1. Linting (must pass)
-python3 -m ruff check src/ tests/
-
-# 2. Type checking (review errors)
-python3 -m mypy src/
-
-# 3. Tests (must pass)
-python3 -m pytest tests/ -x --timeout=30 --ignore=tests/ui/test_tui_chat_loop.py
-
-deactivate
-```
-
-## Common Issues & Fixes
-
-### Unused Imports
-
-```bash
-# Using poe
-uv run poe lint-fix
-
-# Using uv run
-uv run ruff check src/ --fix
-
-# Using manual venv
-source .venv/bin/activate && python3 -m ruff check src/ --fix && deactivate
-```
-
-### Type Errors
-
-```python
-# Error: Incompatible default for argument "x" (default has type "None")
-# Fix: Add | None annotation
-def func(x: str | None = None) -> None: ...
-```
-
-### Test Failures
-
-```bash
-# Using poe
-uv run poe test-verbose
-
-# Using uv run
-uv run pytest tests/test_failing.py -vvs
-
-# Using manual venv
-source .venv/bin/activate && python3 -m pytest tests/test_failing.py -vvs && deactivate
-```
-
-## Project-Specific Guidelines
-
-### Architecture
-
-- **Core**: `src/ayder_cli/core/` - Configuration, context, result types
-- **Tools**: `src/ayder_cli/tools/` - Tool implementations and registry
-- **TUI**: `src/ayder_cli/tui/` - Textual-based terminal UI
-- **Services**: `src/ayder_cli/services/` - LLM providers, tool executor
+`application/runtime_factory.py` provides `create_runtime()` — the single composition root used by both CLI and TUI. It assembles a `RuntimeComponents` dataclass containing: `config`, `llm_provider`, `process_manager`, `project_ctx`, `tool_registry`, `memory_manager`, `system_prompt`.
 
 ### Pluggable Tool System
 
@@ -596,7 +405,7 @@ ayder-cli features a **pluggable tool architecture** with dynamic auto-discovery
 **Adding a New Tool:**
 1. Create `src/ayder_cli/tools/builtins/mytool_definitions.py` with `TOOL_DEFINITIONS` tuple
 2. Implement the tool function in `src/ayder_cli/tools/builtins/mytool.py`
-3. **Auto-discovery and validation handle the rest** — no manual registration, no edits to `validation.py`
+3. **Auto-discovery and validation handle the rest** — no manual registration needed
 
 **Tool Definition Pattern:**
 ```python
@@ -610,42 +419,42 @@ TOOL_DEFINITIONS: tuple[ToolDefinition, ...] = (
         func_ref="ayder_cli.tools.builtins.mytool:my_function",
         parameters={...},
         permission="r",
+        tags=("core",),           # Tag for plugin filtering
+        system_prompt="",         # Optional prompt injected when tool is enabled
     ),
 )
 ```
 
-**Current Tools (28 total):**
-- **Filesystem** (7): list_files, read_file, write_file, replace_string, insert_line, delete_line, get_file_info
-- **Python Editor** (1): python_editor (CST-based structural Python editing)
-- **Search** (2): search_codebase, get_project_structure
-- **Shell** (1): run_shell_command
-- **Memory** (2): save_memory, load_memory
-- **Notes** (1): create_note
-- **Background Processes** (4): run_background_process, get_background_output, kill_background_process, list_background_processes
-- **Tasks** (2): list_tasks, show_task
-- **Environment** (1): manage_environment_vars
-- **Virtual Environments** (5): create_virtualenv, install_requirements, list_virtualenvs, activate_virtualenv, remove_virtualenv
-- **Web** (1): fetch_web
-- **Temporal** (1): temporal_workflow
+**Current Tools (25 total):**
+
+| Category | Tag | Tools |
+|----------|-----|-------|
+| **Filesystem** | `core` | `file_explorer`, `read_file`, `file_editor` |
+| **Search** | `core` | `search_codebase`, `get_project_structure` |
+| **Shell** | `core` | `run_shell_command` |
+| **Memory** | `metadata` | `save_memory`, `load_memory` |
+| **Notes** | `metadata` | `create_note` |
+| **Tasks** | `metadata` | `list_tasks`, `show_task` |
+| **Python Editor** | `python` | `python_editor` (CST-based structural editing) |
+| **Background Processes** | `background` | `run_background_process`, `get_background_output`, `kill_background_process`, `list_background_processes` |
+| **Virtual Environments** | `venv` | `create_virtualenv`, `install_requirements`, `list_virtualenvs`, `activate_virtualenv`, `remove_virtualenv` |
+| **Web** | `http` | `fetch_web` |
+| **DBS** | `dbs` | `dbs_tool` (RAG API for DBS issues) |
+| **Environment** | `env` | `manage_environment_vars` |
+| **Temporal** | `temporal` | `temporal_workflow` |
+
+**Tag System:** Tools are filtered by tags. Default enabled tags: `["core", "metadata"]`. Use `/plugin` in TUI to toggle additional tags at runtime.
 
 **Discovery Features:**
 - Automatic detection of `*_definitions.py` files at import time
 - Duplicate tool name validation
-- Registry-backed input validation (see below)
-- Graceful error handling
-- Zero maintenance overhead
+- Registry-backed input validation via `SchemaValidator`
+- Tool-specific system prompts injected dynamically via `registry.get_system_prompts(tags)`
 
 ### Registry-Backed Validation
 
 `SchemaValidator` (in `application/validation.py`) derives required-argument lists directly from `TOOL_DEFINITIONS_BY_NAME` — the same live registry the executor uses. There is **no hardcoded tool list** to keep in sync.
 
-**Source of truth**: `ToolDefinition.parameters["required"]` in each `*_definitions.py` file.
-
-Consequences:
-- Adding a tool: create the `*_definitions.py` file — validation recognises it automatically.
-- Changing required params: update `ToolDefinition.parameters["required"]` — validation is immediately correct.
-- `SchemaValidator` uses a lazy import (`from ayder_cli.tools.definition import TOOL_DEFINITIONS_BY_NAME` inside the method body) to avoid circular imports at module load time.
-
 ### Key Patterns
 
 1. **Tool Results**: Use `ToolSuccess` and `ToolError` from `core.result`
@@ -653,58 +462,32 @@ Consequences:
 3. **Config**: Use `load_config()` for configuration access
 4. **Console Output**: Use `console` from `ayder_cli.console` for Rich output
 
+## Pre-Commit Checklist
 
+```bash
+# Run all checks (lint + typecheck + test)
+uv run poe check-all
 
-## Resources
-
-- **README.md**: Project overview and usage
-- **.ayder/PROJECT_STRUCTURE.md**: Architecture, module map, TUI structure, import paths ⭐ **Start here for code navigation**
-- **CLAUDE.md**: Redirects to AGENTS.md and PROJECT_STRUCTURE.md
-- **docs/**: Additional documentation
-- **tests/**: Test suites mirror source structure
+# Or individually:
+uv run poe lint      # Must pass
+uv run poe test      # Must pass
+uv run poe typecheck # Review errors (pre-existing issues may exist)
+```
 
 ## Quick Reference
 
-### Priority 1: Using `poe` (Recommended)
-
-| Task | Command | Plugins Used |
-|------|---------|--------------|
-| Install dev deps | `/opt/homebrew/bin/uv pip install -e ".[dev]"` | - |
-| Run tests | `uv run poe test` | timeout, instafail, sugar |
-| Run tests (fast) | `uv run poe test-fast` | + xdist (parallel) |
-| Run tests (coverage) | `uv run poe test-cov` | + cov |
-| Run all tests | `uv run poe test-all` | timeout, instafail, sugar |
-| Run tests (verbose) | `uv run poe test-verbose` | timeout, instafail, sugar |
-| Lint | `uv run poe lint` | - |
-| Lint & fix | `uv run poe lint-fix` | - |
-| Type check | `uv run poe typecheck` | - |
-| Clean caches | `uv run poe clean` | - |
-| All checks | `uv run poe check-all` | lint + typecheck + test |
-
-### Priority 2: Using `uv run` (Fallback)
-
-| Task | Command |
-|------|---------|
-| Run tests | `uv run pytest tests/ -x --timeout=30` |
-| Run tests (fast) | `uv run pytest tests/ -n auto --timeout=30` |
-| Lint | `uv run ruff check src/` |
-| Lint & fix | `uv run ruff check src/ --fix` |
-| Type check | `uv run mypy src/` |
-| Coverage | `uv run pytest tests/ --cov=src/ayder_cli` |
-
-### Priority 3: Manual venv (Last Resort)
-
 | Task | Command |
 |------|---------|
-| Activate | `source .venv/bin/activate` |
-| Run tests | `python3 -m pytest tests/ -x --timeout=30` |
-| Lint | `python3 -m ruff check src/` |
-| Type check | `python3 -m mypy src/` |
-| Deactivate | `deactivate` |
+| Install dev deps | `/opt/homebrew/bin/uv pip install -e ".[dev]"` |
+| Run tests | `uv run poe test` |
+| Run tests (fast) | `uv run poe test-fast` |
+| Run tests (coverage) | `uv run poe test-cov` |
+| Lint | `uv run poe lint` |
+| Lint & fix | `uv run poe lint-fix` |
+| Type check | `uv run poe typecheck` |
+| All checks | `uv run poe check-all` |
+| Clean caches | `uv run poe clean` |
 
 ---
 
-**Remember**: 
-- When in doubt, run `uv run poe check-all`
-- For architecture questions, module relationships, or TUI structure, see [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md)
-- All changes should maintain or improve test coverage
+**Remember**: When in doubt, run `uv run poe check-all`.