# CLAUDE.md

This file provides guidance to Claude Code when working on the factq CLI project.

## Project Overview

**factq** — Your LLM's Local Source of Truth. A local-first knowledge base and verification engine. Python library + CLI + MCP server. Distributed via PyPI (`pip install factq`).

**Key interfaces:** CLI (`factq`), Python library (`import factq`), MCP server (planned).

## Quick Reference

```bash
# Quality gates (run before completing any task)
uv run ruff check src/ tests/    # Lint (auto-fix: --fix)
uv run mypy src/                 # Type check (strict)
uv run pytest tests/ -v          # Tests

# All quality gates at once
uv run ruff check src/ tests/ && uv run mypy src/ && uv run pytest tests/ -v

# CLI testing
uv run factq --version
uv run factq init
uv run factq query "test question"
```

## Architecture

See `docs/ARCHITECTURE.md` for full details.

### Resolution Pipeline

```
Query → KB Lookup (docs/ folder, milliseconds)
  → Deepthink (LLM writes Python to verify, sandbox execution, up to 5 iterations)
    → Commit (verified fact saved back to docs/, git-versioned)
```

### Project Structure

```
factq-cli/
├── src/factq/           # Core package (hatchling, src layout)
│   ├── __init__.py      # Package root, version
│   ├── cli.py           # Click CLI entry point
│   └── py.typed         # PEP 561 type stub marker
├── tests/               # Pytest test suite
├── docs/                # Project documentation
│   ├── ARCHITECTURE.md  # Technical architecture
│   └── adr/             # Architecture Decision Records
├── pyproject.toml       # Project config (Python 3.12+, Apache-2.0)
└── CLAUDE.md            # This file
```

### Key Dependencies

| Tool | Purpose |
|------|---------|
| **uv** | Package manager, venv (Python 3.12) |
| **hatchling** | Build backend |
| **click** | CLI framework |
| **rich** | Terminal formatting |
| **pydantic** | Data models |
| **ruff** | Linter |
| **mypy** | Type checker (strict mode) |
| **pytest** | Test runner |

## Common Commands

Always use `uv run python` or `uv run pytest` — never bare `python` or `pytest`.

```bash
# Install dependencies
uv sync

# Lint
uv run ruff check src/ tests/

# Type check
uv run mypy src/

# Run tests
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ -v --cov=src --cov-report=term-missing

# Build package
uv run python -m build
```

## Quality Gates

**All must pass before task completion:**

| Gate | Command | Requirement |
|------|---------|-------------|
| Lint | `uv run ruff check src/ tests/` | Zero errors |
| Types | `uv run mypy src/` | Zero errors |
| Tests | `uv run pytest tests/ -v` | All pass |

**If any fail, you are NOT DONE.**

## Code Style & Conventions

- **Python 3.12+**, line length 100
- Type annotations required on all functions (mypy strict)
- Ruff rules: `E, F, I, N, UP, B, SIM, TCH`
- License: Apache-2.0
- Only add dependencies with permissive licenses (Apache 2.0, MIT, BSD)

### Python Conventions

```python
from __future__ import annotations    # 1. Future
import sys                            # 2. Stdlib
from pydantic import BaseModel        # 3. Third-party
from factq.core import Engine         # 4. Local
```

- Classes: `PascalCase` | Functions/variables: `snake_case` | Constants: `UPPER_SNAKE_CASE`
- Prefer `list[str]` over `List[str]`, `str | None` over `Optional[str]`
- Commit format: `<type>: <description>` (feat/fix/test/refactor/docs/chore)

## Development Principles

### Red / Green / Refactor — MANDATORY

| Phase | Action |
|-------|--------|
| RED | Write failing test first |
| GREEN | Minimal code to pass |
| REFACTOR | Clean up, tests stay green |

### SOLID

| Principle | Rule |
|-----------|------|
| **S**ingle Responsibility | One class, one job |
| **O**pen/Closed | Extend via composition |
| **L**iskov Substitution | Subtypes honor contracts |
| **I**nterface Segregation | Focused interfaces |
| **D**ependency Inversion | Depend on abstractions |

## Git Rules

- NEVER commit without explicit user request
- NEVER add Co-Authored-By lines
- NEVER amend unless explicitly asked
- Stage specific files, not `git add -A`

## Key Documents

| Document | Purpose |
|----------|---------|
| `docs/ARCHITECTURE.md` | Technical architecture and component design |
| `docs/adr/` | Architecture Decision Records |
| `docs/adr/001-rlm-over-rag.md` | Why RLM over RAG |
