<!-- SAAR:AUTO-START -->
# AGENTS.md -- saar

Generated by [saar](https://getsaar.com). Re-run `saar . --format agents` to update auto-detected sections.

809 functions, 137 classes, 65 files.

**Languages:** python (58 files), typescript (5 files), javascript (2 files)


## Frontend

**Stack:** React + TypeScript + Vite
- Package manager: `bun` -- always use `bun install`, never npm/yarn
- Styling: Tailwind CSS -- no raw CSS files
## Coding Conventions

- Functions: `snake_case`
- Classes: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
- Files: `snake_case`

Key project imports:
```
from saar.models import CodebaseDNA
import typer
from rich.console import Console
from dataclasses import dataclass, field
import tree_sitter_python as tspython
```

## Logging

- Use `logging.getLogger(__name__)` -- never bare `print()`

## Critical Files

These files have the most dependents in the codebase. Understand them before making changes.

- `saar/models.py` (27 dependents)
- `saar/cli.py` (10 dependents)
- `saar/extractor.py` (8 dependents)
- `saar/formatters/agents_md.py` (7 dependents)
- `saar/interview.py` (5 dependents)
- `saar/differ.py` (5 dependents)
- `saar/formatters/_tribal.py` (4 dependents)
- `saar/formatters/claude_md.py` (4 dependents)

## Auth

- Protected endpoints use `Depends(reusable_oauth2)` — never bypass with manual header parsing


> [31 lines omitted -- run `saar extract --verbose` for full output]
## How to Verify Changes Work

Backend: `pytest tests -v` | Frontend: `bun run build`

Run these before considering any change done.

## Tribal Knowledge

*Captured via `saar` interview -- human knowledge static analysis cannot detect.*

**This project:** CLI tool that extracts codebase DNA and generates AI context files (AGENTS.md, CLAUDE.md, .cursorrules) -- no server, no account, no API key required

### Never Do

- Always run tests inside venv: `source venv/bin/activate && pytest tests/ -q` -- system Python missing typer causes collection errors
- 548 tests must pass before any commit
- Never push directly to OpenCodeIntel/saar main. Never commit venv/ dist/ __pycache__
- Never add external infrastructure dependencies (no Supabase, Redis, network calls in core path)
- Never add command logic to cli.py -- it only registers app.command() calls. Logic goes in saar/commands/
- Never add extraction logic to extractor.py -- DNAExtractor delegates to saar/extractors/ modules
- benchmark/ contains OPE-99 results -- never delete benchmark_results.json or benchmark_report.md
- saar has NO web auth -- any detected Depends(reusable_oauth2) is a false positive from test fixtures
- Always run `ruff check saar/ tests/ && pytest tests/ -q` before committing

### Domain Vocabulary

- DNA = extracted architectural patterns of a codebase (not genetic material)
- Tribal knowledge = context only humans can provide: gotchas, domain terms, verification workflows -- static analysis cannot detect this
- SAAR:AUTO-START/END markers = preservation markers separating auto-generated from human-written sections in generated files
- budget = line cap on generated output (default 100 lines, --verbose for full)

### Verification Workflow

`source venv/bin/activate && pytest tests/ -q` -- 548 tests must pass. Then: `saar extract . --no-interview` to verify CLI output is clean

### Off-Limits Files

> AI must never modify these:

- saar/models.py -- core data contract, CodebaseDNA and all dataclasses, never modify without discussion

### Additional Context

This repo dogfoods itself -- after any formatter change regenerate all context files: saar extract . --force --no-interview
<!-- SAAR:AUTO-END -->
