# Agent instructions

<!--
Template for a project built on the cryptopeer stack: https://cryptopeer.net/skills/
Save it as AGENTS.md (Codex, Cursor, others), CLAUDE.md (Claude Code) or
SYSTEM.md (Boubou). Fill in the <…> blanks and delete what the project does not use.
-->

## What this project is

<One paragraph: what the app does, who the peers are (phones, servers,
browsers), and how they reach each other.>

## Stack

This project builds on the cryptopeer stack (https://cryptopeer.net). These
are not the upstream libp2p packages, and their APIs differ: load the matching
skill before writing code against a package, and check identifiers against the
package source rather than writing them from memory.

| Package | Version | Skill |
|---|---|---|
| dart_libp2p | <^4.12.0> | dart-libp2p-host |
| dart_udx | <^4.3.0> | udx-dart |
| <…> | <…> | <…> |

Skills are installed in <.claude/skills/ | .agents/skills/ | skills/>. To
update them: `curl -fsSL https://cryptopeer.net/skills/install.sh | sh -s -- --agent <agent>`.

## Peers and protocols

- Our protocol IDs: <`/myapp/sync/1.0.0`, …>. They are a contract with
  deployed peers: never change one or its message format in place. Add a new
  version and keep serving the old one.
- Transports we listen on: <`/ip4/0.0.0.0/udp/0/udx`, …>.
- Relays / bootstrap peers: <where they are configured; never hard-code them>.
- Ricochet servers: <which, and where the config lives>.

## Identity and secrets

- The host key is stored in <path or keystore>. Load it on start; generate one
  only on first run. A new key is a new peer ID and breaks <mailboxes, ACLs,
  DHT records, …>.
- Never log, print or commit private keys, seeds or relay credentials.
- Authorise by the peer ID of the connection (the remote peer of the stream),
  never by an ID a message claims.

## Rules

- Cap the size of every message read from a peer and put a timeout on every
  network operation.
- Close hosts, streams, subscriptions and sockets you open, in tests too.
- Upgrade UDX on all peers together (v3 does not talk to v2, and the failure
  is silent).
- Keep Noise on outside tests.

## Commands

- Get dependencies: <`dart pub get` / `flutter pub get` / `go mod download` / `npm ci`>
- Unit tests: <`dart test` / `go test ./...` / `npx vitest run`>
- Network tests (two or more hosts on loopback): <command, and how long they take>
- Lint: <`dart analyze` / `go vet ./...`>
- Run locally: <command>

Before finishing a task that touches networking, run the network tests, not
only the unit tests.

## Where things are

- <lib/net/: host setup and protocol handlers>
- <lib/protocols/: one file per protocol>
- <test/net/: multi-host tests>