diff --git a/.gitignore b/.gitignore
index 204e9fd..4ae1f0e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,10 @@
 __pycache__/
 *.pyc
 .venv/
+build/
 dist/
 *.egg-info/
+.omx/
 .pytest_cache/
 .ruff_cache/
 .coverage
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d72ff16
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# PortkeyDrop — AI Agent Guidelines
+
+Cross-platform SFTP file transfer tool with screen reader accessibility. Package: `portkeydrop`. Config dir: `~/.portkeydrop`.
+
+## Quick Reference
+
+```bash
+uv run ruff check --fix . && uv run ruff format .   # Lint + format
+uv run pytest                                        # Run tests (132 tests)
+uv run pytest tests/test_file.py::test_func          # Single test
+uv run pytest -n auto                               # Parallel tests
+```
+
+## Branch Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Stable releases |
+| `dev` | Active development — PRs go here |
+| `feature/*` | Feature work → PR to dev |
+| `fix/*` | Bug fixes → PR to dev |
+
+## Commit Format
+
+```
+type(scope): description
+Types: feat, fix, docs, style, refactor, test, chore
+```
+
+## PR Rules
+
+- Always PR to `dev`, never `main`
+- Title in Conventional Commit format
+- Body via `--body-file` (never inline `--body`)
+- Do not auto-merge
+
+## Key Notes
+
+- Three-tier password storage: keyring > encrypted vault > none
+- Accessibility: all interactive UI elements need aria labels
+- SFTP operations use `asyncssh`