docs: rename GEMINI.md to AGENTS.md with updated guidelines

AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository. Human contributors should also read [docs/contributing.md](docs/contributing.md), [docs/development.md](docs/development.md), and [docs/testing.md](docs/testing.md), which are the source of truth.
+
+## Project summary
+
+Config Sync synchronizes configurations and policies from a source of truth (Git repository, OCI image, or Helm chart) to a Kubernetes cluster, ensuring consistency at scale. It simplifies and automates configuration management across single or multi-cluster environments, managing both cluster-scoped and namespace-scoped resources.
+
+**Key Technologies & Architecture:**
+- **Language & Frameworks:** Go, Kubernetes, Kubebuilder / Controller Runtime, Kustomize.
+- **Core Custom Resources:** `RootSync` (cluster-scoped synchronization) and `RepoSync` (namespace-scoped synchronization).
+- **Reconciler Manager:** Controller component that manages the lifecycle of individual reconciler deployments.
+- **Reconcilers:** Specialized controllers spawned for each sync target that watch the upstream source and apply manifests to the cluster.
+- **Admission Webhook:** Validates configuration and state changes for Config Sync custom resources.
+- **Nomos CLI:** Command-line interface for inspecting status, troubleshooting, and interacting with Config Sync deployments.
+
+## Repository layout
+
+| Path | What lives there |
+| --- | --- |
+| [cmd/](cmd/) | Main entrypoints for controllers (`reconciler-manager`, `reconciler`, `admission-webhook`) and the `nomos` CLI. |
+| [pkg/](pkg/) | Core implementation logic: reconcilers, git/OCI sync logic, manifest parsers, validation logic, and webhook handlers. |
+| [manifests/](manifests/) | Base Kubernetes manifests and Kustomize configurations used to deploy Config Sync components. |
+| [e2e/](e2e/) | End-to-end test framework and test suites (Go-driven, runnable against kind or GKE). |
+| [docs/](docs/) | Documentation for usage, installation, contributing, development, and testing. |
+| [examples/](examples/) | Sample Git repositories and configurations used for tutorials and verification. |
+| [scripts/](scripts/) | Shell scripts for CI, verification, and auxiliary build tasks. |
+| [build/](build/) | Build setups, container entrypoints, base Dockerfiles, and build dependencies. |
+
+When in doubt about ownership or review requirements, check the nearest `OWNERS` file.
+
+## Build, test, lint
+
+All primary build and testing workflows run through the [Makefile](Makefile). Prefer using `make` targets over invoking native tools directly to maintain consistency with CI.
+
+- `make build-cli` — Compiles the `nomos` CLI binary.
+- `make build-manifests` — Generates deployment manifests into `.output/staging/oss`.
+- `make build-images` — Builds required Docker container images for Config Sync controllers.
+- `make config-sync-manifest` — Builds images and manifests from source in a single step.
+- `make test` — Runs fast Go unit tests.
+- `make test-e2e-kind` — Runs end-to-end validation against a local kind cluster (requires pre-installing kind via `make install-kind`).
+
+For detailed testing parameters (including running targeted E2E test regexes or reusing test cluster environments), consult [docs/testing.md](docs/testing.md).
+
+## Agent Skills
+
+Shared agent skills and custom automations for working in this repository should be organized within an `.agents/` directory following emerging repository standards.