From f2fdda913d35f5ee20540964c7fc238084f72efc Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 21 Sep 2026 18:39:46 -0300
Subject: [PATCH] docs: add repository guidance

Signed-off-by: Vitor Mattos <vitor@php.rio>
---
 AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9e00fb2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,40 @@
+<!--
+SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Agent guidance
+
+## Purpose
+
+This repository owns the organization-agnostic engine that discovers repositories and reconciles declarative GitHub repository governance, rulesets and supported repository metadata.
+
+## Boundaries
+
+- Organization/product policy belongs in caller-owned `governance.config.json`, not hard-coded in the engine.
+- Keep dry-run as the safe default; mutation must remain explicit.
+- Repository metadata reconciliation may manage GitHub settings such as description, homepage and topics.
+- File content such as licenses, README files and `AGENTS.md` remains version-controlled in each repository.
+- Release automation belongs in `LibreCodeCoop/github-workflows`, not here.
+
+## Quality gates
+
+Run or rely on CI for:
+
+- TypeScript build/type checks;
+- Vitest;
+- actionlint;
+- zizmor;
+- CodeQL;
+- REUSE compliance.
+
+## Security
+
+- Use short-lived GitHub App tokens with the narrowest repository scope.
+- Do not centralize caller credentials in this repository.
+- Do not weaken rulesets silently to make reconciliation pass.
+- Keep third-party actions pinned to immutable SHAs.
+
+## SPDX / REUSE
+
+New repository-owned files use AGPL-3.0-or-later and must satisfy REUSE/SPDX checks.