docs: expand AGENTS.md with full build, architecture, and convention details

Author: Coding-Dev-Tools

AGENTS.md

@@ -1,13 +1,30 @@
 # deadcode
 
-Repo guide for agents.
+## Purpose
+CLI tool to detect and auto-remove unused exports, dead routes, and orphaned CSS in TypeScript/React/Next.js projects.
 
-## Workflow
-- Use `pytest` for tests.
-- Use `ruff` for lint/format.
-- Build/publish via GitHub Actions in `.github/workflows/`.
+## Build & Test Commands
+- Install: `pip install -e .` or `pip install git+https://github.com/Coding-Dev-Tools/deadcode.git`
+- Test: `pytest tests/` (or `python -m pytest tests/ -v --tb=short`)
+- Lint: `ruff check src/ tests/`
+- Format: `ruff format src/ tests/`
+- Build: `pip install build twine && python -m build && twine check dist/*`
+- CLI check: `deadcode --help`
+
+## Architecture
+Key directories:
+- `src/deadcode/` — Main package (CLI, scanner, config)
+- `tests/` — Test suite
+- `.github/workflows/` — CI/CD (auto-code-review.yml, ci.yml, publish.yml)
 
 ## Conventions
-- Package code under `src/deadcode` per `pyproject.toml` packaging config.
-- Keep branches `improve/<repo>-<timestamp>` for structural fixes.
-- Do not modify dependencies without updating `pyproject.toml`.
+- Language: Python 3.10+
+- Test framework: pytest (with coverage)
+- CI: GitHub Actions (matrix: Python 3.10, 3.11, 3.12, 3.13)
+- Linting/formatting: ruff (line-length 120, target py310)
+- Package layout: src/ layout with setuptools
+- Type checking: py.typed included
+- Dependencies: click, rich, pathspec, pyyaml
+- CLI entry point: deadcode.cli:cli
+- Default branch: master
+- Branch naming: `improve/<repo>-<timestamp>` for structural fixes