Add AGENTS.md agent guidance

Co-Authored-By: Claude Fable 5 <[email protected]>

AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md — BitGate (Nostr-Governance)
+
+## Purpose
+
+BitGate is a headless governance SDK for Nostr apps: moderation and access
+control expressed as four decision dimensions (ranking, visibility,
+interaction, transaction). The engine carries no thresholds of its own —
+applications supply a policy definition; the engine supplies precedence,
+aggregation, composition, and explanation.
+
+## Repository map
+
+- `packages/` — npm workspaces: `core` (pure evaluation, zero deps), `nostr`
+  (codecs), `runtime`, `verify` (signature verification), `testing`
+  (conformance harness), `widget`, `standalone`, `bitvid-compat`, `site`.
+- `tests/` — unit, conformance, performance, and security test suites.
+- `examples/` — runnable integration examples (workspace members).
+- `fixtures/` — characterization corpus data.
+- `docs/` — security model, integration guide, NIPs, ADRs, TODO.
+- `scripts/` — corpus/fixture tooling and `verify-no-reference-imports.mjs`.
+
+## Build / test / validate
+
+Requires Node >= 22. Install with `npm ci` (or `npm install`).
+
+- Run `npm test` — unit tests plus conformance suite (vitest).
+- Run `npm run test:unit` or `npm run test:conformance` for one half.
+- Run `npm run lint` — reference-import check plus typechecking.
+- Run `npm run typecheck` for types only.
+- Run `npm run build:types`, `npm run build:widget`, `npm run build:standalone`,
+  or `npm run build` for everything including the site.
+- CI (`.github/workflows/ci.yml`) runs `npm run lint`, `npm test`, and
+  `npm run build:types` on Node 22 — match that locally before pushing.
+
+## Conventions
+
+- `@bitgate/core` stays dependency-free: no I/O, no browser globals. The
+  `verify` package exists precisely so core never imports crypto.
+- `scripts/verify-no-reference-imports.mjs` (part of `lint`) enforces import
+  boundaries — do not work around it.
+- ESM throughout (`"type": "module"`); TypeScript via JSDoc/`.d.ts` builds.
+
+## Backlog
+
+Open work is tracked in `docs/TODO.md`.
+
+## Security
+
+- Everything arriving from a relay is untrusted input; `event.pubkey` is an
+  unauthenticated claim until a signature is verified. Administrative state
+  fails closed without `verifySignature`. See `docs/security.md` before
+  touching ingest, authorship, or verification paths.
+- Never commit secrets or private keys; fixtures must contain only public,
+  already-published event data.
+
+## Change policy
+
+- Keep diffs minimal and scoped to the task.
+- Behavior changes must update the corresponding tests (including conformance
+  fixtures where applicable).
+- Never weaken, skip, or delete tests to make a change pass.