From c43e4d5526391c97d977f258ec54c2c1b7790602 Mon Sep 17 00:00:00 2001
From: Orinks <orin8722@gmail.com>
Date: Sat, 9 May 2026 00:28:38 -0400
Subject: [PATCH] chore(repo): track agent guidance and ignore local artifacts

Keep generated build output and local OMX runtime state out of status while preserving contributor-facing agent instructions in the repository.

Constraint: build/ and .omx/ are local/generated artifacts; AGENTS.md is intended contributor guidance.

Confidence: high

Scope-risk: narrow

Directive: Keep local runtime state ignored unless a future repo-owned OMX artifact is intentionally introduced.

Tested: git check-ignore -v build .omx

Not-tested: Runtime behavior, docs-only repository hygiene change.

Co-authored-by: OmX <omx@oh-my-codex.dev>
---
 .gitignore |  2 ++
 AGENTS.md  | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 AGENTS.md

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`