docs: streamline and verify AGENTS.md guidance

AGENTS.md

@@ -0,0 +1,9 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Repository guidance
+
+- Nested `AGENTS.md` files hold area guidance. Before changing files under a directory, read each `AGENTS.md` between that directory and this one.
+- `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, except `gen/README.md`, which documents the tree.
+- Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their output. Read [gen/README.md](gen/README.md) when regenerating those artifacts.
+- New files need the SPDX header; `make lint-license` checks it.
+- Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun them without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack.

cli/AGENTS.md

@@ -1,27 +1,14 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# IBC CLI Development Guide for AI Agents
+# IBC CLI
 
-- Use `make lint-fix` to auto-format and lint code before finishing work.
-- Don't add verbose comments. Be concise.
-- `gen/` at the repository root holds generated code only, and its layout is fixed by an ADR — don't
-  move it or put anything handwritten there. Generator scripts belong in the root `scripts/`
-  directory, not beside their output. The one exception is `gen/README.md`, which documents the tree.
-- Repository-wide black-box e2e lives in `../e2e`, with its harness in
-  `../e2e/internal/harness` as a separate Go module. The real relayer submits packets through
-  ICS26Router with attestation proofs signed by harness-managed attestors. Keep
-  `make -C e2e test` green when changing that transport contract.
+- Interfaces listed in `.mockery.yaml` have generated mocks. After changing one, run
+  `make codegen-mocks` from `cli/`; CI does not regenerate them.
+- `make -C e2e test` defaults to `E2E_MODE=fast`, which skips tests that require Besu without
+  failing; `E2E_MODE=complete` runs them. See
+  [Running the acceptance tests](../e2e/README.md#running-the-acceptance-tests).
 
 ## Documentation generated from this code
 
-The reference pages under `docs/6-ibc-cli/` carry tables generated from this
-directory. **If you change anything here, the documentation must be regenerated
-before the pull request is opened**, and the regenerated pages belong in the
-same pull request as the code.
-
-Follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md).
-It covers what to run, what the generator refuses and why, and what you may
-write yourself.
-
-Never hand-edit between a `<!-- GEN:... START -->` marker and its `END`: the
-next run overwrites it.
+When changing commands or flags, configuration, cited behavior, or build inputs represented in the
+CLI reference pages, follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md).

cli/internal/server/AGENTS.md

@@ -1,15 +1,6 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# ConnectRPC Guide for AI Agents
+# ConnectRPC adapters
 
-Development flow:
-1. Update raw protos in `proto/cli/*`.
-2. Run `make codegen` (proto and mocks included).
-3. Implement ConnectRPC handlers in `attestor_handler.go` or `relayer_handler.go`.
-4. Add missing `AttestorService`/`RelayerService` methods if needed.
-   - Use idiomatic Go: `ctx` first.
-   - If a service method needs more than 3 args, use a DTO struct.
-5. Keep `server/` as an adapter only:
-   - Convert ConnectRPC/proto types to service DTOs.
-   - Call the service interface.
-   - Map domain errors to `connect.Code*`.
+Keep this package as a transport adapter: convert ConnectRPC/proto types to service DTOs, call the
+service interface, and map domain errors to `connect.Code*`.

cli/internal/store/AGENTS.md

@@ -1,54 +1,16 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# Store guidelines for AI Agents
+# Store
 
 `store.Store` is the single entrypoint for other packages that rely on DB.
 
-## I. Creating migrations
-
-To create a migration, run the script from the project's root (./cli)
-
-```bash
-go run scripts/migratenew.go add-packet-index
-✔︎ Created /path/to/ibc/cli/internal/store/migrations/sqlite/002-add-packet-index.sql
-✔︎ Created /path/to/ibc/cli/internal/store/migrations/postgres/002-add-packet-index.sql
-```
-
-The script prints absolute paths and assigns the next migration number automatically.
-
-Edit both `migrations/sqlite/*.sql` and `migrations/postgres/*.sql`; keep behavior identical, syntax dialect-specific.
-
-## II. Query creation, code generation
-
-For types & queries generation, `sqlc` tool is used.
-
-When creating `sqlc` SQL queries in `queries/*`, use "macros" to build unified files that 
-can be used both for sqlite and postgres. Example:
-
-```sql
--- name: GetAuthorByName :one
-SELECT *
-FROM authors
-WHERE lower(name) = sqlc.arg(name);
--- "sqlc.arg" is a macro, "sqlc.narg" is similar, but makes a param nullable
--- macros docs: https://docs.sqlc.dev/en/latest/reference/macros.html
-
--- >>> EXPANDS TO >>>
-
--- name: GetAuthorByName :one
-SELECT *
-FROM authors
-WHERE lower(name) = ?;
-```
-
-- (re)generate bindings with `make codegen-sql`.
-- Don't edit generated files in `repository/sqlite` or `repository/postgres`.
-
-### III. Unified repository layer
-
-After ensuring that the new migration is in place and the sqlc models and queries have been generated:
-
-- Add public persistence methods to `Repository` interface in `store.go`. Use idiomatic Go
-- Implement every method in both `store_sqlite.go` and `store_postgres.go`.
+- From `cli/`, create paired migrations with `go run scripts/migratenew.go <name>`. Edit both
+  `migrations/sqlite/` and `migrations/postgres/`; keep their behavior equivalent while using each
+  dialect's syntax.
+- For persistence or schema changes, test against both backends from `cli/`. PostgreSQL tests are
+  skipped unless `TEST_POSTGRES=true`; enabled tests require working Docker. Report any backend
+  you could not verify.
+- `queries/` is shared by both dialects: write portable SQL with `sqlc.arg` and `sqlc.narg`, then
+  run `make codegen-sql` from `cli/`.
+- Add public persistence methods to the `Repository` interface in `store.go`, not to `Store`.
 - Return domain structs from `store.go`, not generated sqlc row types.
-- Implement basic input validation. if method arg is a struct, implement `.Validate() error` for it

docs/6-ibc-cli/5-configuration.md

@@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next
 run overwrites whatever is there, so a hand edit looks like a fix and is not.
 The prose around them is written by hand and is yours to change.
 
-After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md
-before opening a pull request.
+When changing commands, configuration, APIs, or cited behavior represented on
+these pages, follow docs/6-ibc-cli/tools/AGENTS.md.
 -->
 
 <!-- GEN:notice END -->

docs/6-ibc-cli/6-cli-commands.md

@@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next
 run overwrites whatever is there, so a hand edit looks like a fix and is not.
 The prose around them is written by hand and is yours to change.
 
-After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md
-before opening a pull request.
+When changing commands, configuration, APIs, or cited behavior represented on
+these pages, follow docs/6-ibc-cli/tools/AGENTS.md.
 -->
 
 <!-- GEN:notice END -->

docs/6-ibc-cli/7-api.md

@@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next
 run overwrites whatever is there, so a hand edit looks like a fix and is not.
 The prose around them is written by hand and is yours to change.
 
-After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md
-before opening a pull request.
+When changing commands, configuration, APIs, or cited behavior represented on
+these pages, follow docs/6-ibc-cli/tools/AGENTS.md.
 -->
 
 <!-- GEN:notice END -->