From 456f14ef97289e7b690ceeac487ae2e9982c36d2 Mon Sep 17 00:00:00 2001
From: Talha <tamjad91@gmail.com>
Date: Thu, 6 Aug 2026 02:46:43 +0500
Subject: [PATCH] chore(docs): add contributor agent guidance

---
 AGENTS.md | 31 +++++++++++++++++++++++++++++++
 CODEX.md  | 14 ++++++++++++++
 2 files changed, 45 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CODEX.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5fb1c80
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,31 @@
+# Contributor agent guide
+
+VidXP is a Python application with CLI, HTTP, MCP, and Desktop surfaces that
+share the same application contracts. Read
+[`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) before making changes.
+
+## Working in the repository
+
+- Keep pull requests focused on one outcome and preserve unrelated work.
+- Put shared behavior in the application or control plane; keep CLI, HTTP,
+  MCP, and Desktop code as thin adapters.
+- Keep capability-specific models, schemas, dependencies, indexing, and search
+  logic under `src/vidxp/capabilities/`.
+- Do not commit generated environments, model weights, media, indexes, build
+  outputs, or local data.
+- Follow the Conventional Commit and release-note rules in the contributing
+  guide. State explicitly when a change is internal-only.
+
+## Validation
+
+Run the smallest relevant checks while developing, then the applicable checks
+from the contributing guide before submitting a pull request. Common checks:
+
+```bash
+uv run --no-sync ruff check .
+uv run --no-sync pytest -q
+npm --prefix desktop run check
+```
+
+Do not describe mocked tests as end-to-end validation. Report the exact
+commands run and any required validation that could not be completed.
diff --git a/CODEX.md b/CODEX.md
new file mode 100644
index 0000000..b5c2fc5
--- /dev/null
+++ b/CODEX.md
@@ -0,0 +1,14 @@
+# Codex contributor notes
+
+Start with [`AGENTS.md`](AGENTS.md) and
+[`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md).
+
+1. Inspect the affected implementation, shared contracts, and existing tests.
+2. Make the smallest coherent change at the correct architecture boundary.
+3. Reuse repository tooling and generated-file workflows instead of manually
+   recreating derived artifacts.
+4. Run validation appropriate to the changed surface.
+5. Summarize the outcome, exact validation performed, and remaining risks.
+
+Ask before introducing a new dependency, migration, public contract change, or
+architecture direction that is not already established by the repository.