docs: add CLAUDE.md and Agents.md for AI coding assistant guidance

.gitignore

@@ -30,3 +30,6 @@ _testmain.go
 *.prof
 
 .DS_Store
+
+AGENTS.md
+CLAUDE.md

AGENTS.md

@@ -0,0 +1,163 @@
+# AGENTS.md
+
+Project instructions for **AI coding assistants and agents** (OpenAI Codex, Cursor, GitHub Copilot, Claude Code, and similar tools). This file is the canonical source of shared project instructions; `CLAUDE.md` imports this file for Claude Code.
+
+## Project overview
+
+Bee is the reference Go implementation of an Ethereum Swarm node. It implements decentralized storage and communication: content-addressed chunk storage, Kademlia-based routing, postage stamp accounting, push/pull syncing, PSS messaging, feeds, and storage incentives (redistribution game).
+
+**Module**: `github.com/ethersphere/bee/v2`
+
+**Go version**: 1.26 (see `go.mod`)
+
+**License**: BSD 3-clause (see `LICENSE`)
+
+Human-oriented contributing docs: `CONTRIBUTING.md`, `CODING.md`, `CODINGSTYLE.md`, `README.md`.
+
+## Guidelines
+
+Keep changes **minimal and focused**. Only touch code that belongs to the task. Do not refactor unrelated code, rename symbols for style only, or mix unrelated fixes in one commit or PR.
+
+Read **`CONTRIBUTING.md`**, **`CODING.md`**, and **`CODINGSTYLE.md`** for process, patterns, and style. Prefer matching existing naming, types, imports, and log style in the files you edit.
+
+Do **not** add, remove, or update `go.mod` dependencies unless the task **explicitly** requires it or the person asking for the work **explicitly** requests a dependency change.
+
+Handle errors and logging the way this repo does: propagate errors with context (`fmt.Errorf("…: %w", err)`), avoid logging and returning the same error, and use structured logging with clear operator vs developer levels (see `CODING.md`).
+
+Prefer **`package foo_test`** tests, **`export_test.go`** when you must export internals, and **`t.Parallel()`** only where it is safe. Add or update tests when behavior changes. Integration tests use **`-tags=integration`**.
+
+## Pre-commit checklist
+
+Before you finish a change set (especially before a commit or PR), run these and fix failures:
+
+1. **Formatting** — `make format` (gofumpt + gci; see `CODING.md`).
+2. **Compile** — `make build` (all packages) and, when you need the binary artifact, `make binary` (`dist/bee`, `CGO_ENABLED=0`).
+3. **Tests** — `make test` (unit tests, `-failfast`). For a single package use `go test ./pkg/<name>/...`. Use `make test-race` when concurrency is central to the change. Use `make test-integration` only when you touch integration-tagged code.
+4. **Static checks** — `make lint` and `make vet` (see `.golangci.yml`).
+
+CI pipelines may use `make test-ci` / `make test-ci-race` (see `Makefile` for flags).
+
+## Dev commands (quick reference)
+
+```bash
+make binary     # dist/bee
+make build      # compile all packages
+make test       # unit tests
+make test-race  # unit tests + race detector
+make lint       # golangci-lint (see .golangci.yml)
+make vet        # go vet
+make protobuf   # regenerate *.pb.go after changing .proto files
+```
+
+## Architecture
+
+### Entry point and CLI
+
+Binary built from `cmd/bee/main.go`. CLI uses Cobra + Viper:
+
+- `bee start` — full or light node (`cmd/bee/cmd/start.go`)
+- `bee init` — initialize data directory
+- `bee deploy` — deploy smart contracts
+- `bee db` — database management
+- `bee version` — print version info
+
+Configuration: option constants in `cmd/bee/cmd/cmd.go`. Viper reads CLI flags, environment variables (`BEE_` prefix), and YAML config.
+
+### Node bootstrap
+
+`pkg/node/node.go` is the main orchestrator. `NewBee()` wires subsystems via dependency injection; avoid global mutable state. The `Bee` struct holds service references and provides `Shutdown()` for teardown.
+
+### HTTP API
+
+- Router: `gorilla/mux` in `pkg/api/router.go`
+- Route groups in `Mount()`:
+  - `mountTechnicalDebug()` — `/node`, `/addresses`, `/health`, `/readiness`, `/metrics`, `/loggers`, pprof
+  - `mountBusinessDebug()` — topology, accounting, settlements, stamps management
+  - `mountAPI()` — `/bytes`, `/chunks`, `/bzz`, `/feeds`, `/soc`, `/stamps`, `/tags`, `/pins`, `/pss`, `/grantee`
+- `checkRouteAvailability` can block endpoints during sync
+- OpenAPI: `openapi/Swarm.yaml` (API versioning follows SemVer there; the main Bee release version does not)
+- Endpoints exist at root (e.g. `/bytes`) and under `/v1/` (e.g. `/v1/bytes`)
+
+### P2P networking
+
+- Transport: libp2p (`pkg/p2p/libp2p/`)
+- Wire formats: protobuf (gogo) — each protocol area has a `pb/` directory with `.proto` and `doc.go` (`go:generate` calling `protoc` + `--gogofaster_out`)
+- Important protocol packages: `pushsync`, `pullsync`, `retrieval`, `pingpong`, `hive`, `pricing`
+
+### Storage
+
+- Chunk types: CAC (`pkg/cac/`), SOC (`pkg/soc/`)
+- Interfaces: `pkg/storage/` (`Putter`, `Getter`, `Hasser`, `Deleter`)
+- Local store: `pkg/storer/` (reserve, cache, upload, pinning)
+- Blob engine: `pkg/sharky/`
+- BMT: `pkg/bmt/`
+- State: `pkg/statestore/` (LevelDB); `pkg/shed/` (typed LevelDB layer)
+
+### Postage and incentives
+
+- `pkg/postage/` — batches, stamps, services
+- `pkg/postage/listener/` — on-chain events
+- `pkg/postage/postagecontract/` — contract interaction
+- Stamps: batch ID, depth (capacity), amount (per-chunk value)
+- `pkg/storageincentives/` — redistribution / storage incentive game
+
+## Key domain concepts
+
+- **Address** — 32-byte hash (`pkg/swarm/`). Chunk and overlay addresses; proximity is XOR-based (more shared prefix bits = closer), not lexicographic ordering.
+- **Chunk** — 4096 bytes of data (`ChunkSize = SectionSize * Branches = 32 * 128`), plus 8-byte span (`SpanSize`); `ChunkWithSpanSize = 4104`.
+- **CAC** — content-addressed chunk; address from BMT root of data.
+- **SOC** — single owner chunk; address from owner + id, with signature.
+- **PO** — proximity order (shared prefix bits). `MaxPO = 31`, `ExtendedPO = 36`.
+- **Neighborhood** — prefix / responsibility region for storage and sync.
+- **Kademlia** — routing table over XOR distance (`pkg/topology/`).
+- **Postage stamp** — payment signal attached to chunks.
+- **Push sync / pull sync** — push new data toward neighborhood; pull historical sync between peers.
+- **Redistribution** — incentive game proving reserve storage.
+
+## Coding conventions (summary)
+
+### Copyright (goheader)
+
+Every `.go` file starts with:
+
+```go
+// Copyright <year> The Swarm Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+```
+
+### Errors, logging, concurrency
+
+- Propagate errors; do not log and return the same error. Use `fmt.Errorf("context: %w", err)`. Avoid stacking "failed to" prefixes.
+- Sentinel errors: `var ErrFoo = errors.New("package: description")` — identity only, compared with `errors.Is`.
+- Typed errors: a struct implementing `error` with exported fields, inspected with `errors.As` when callers need data about the failure.
+- Logging: separate operator-facing (`Error`/`Warning`) from developer detail (`Debug`, V-levels). Keys: `lower_snake_case`, specific names. Runtime log tuning: `/loggers` API.
+- Every goroutine needs a clear shutdown path. Channels: prefer unbuffered or size 1 unless strongly justified; an owning goroutine sends or closes.
+
+### Testing
+
+- Prefer external test packages: `package foo_test` not `package foo`.
+- `export_test.go` in the real package to export symbols only for tests.
+- Use `t.Parallel()` where safe. Avoid the word `fail` in test names. Integration: `-tags=integration`. Prefer `t.Fatal` / `t.FailNow` over `panic` in tests.
+
+### Style and tooling
+
+- American English (e.g. marshaling, canceled).
+- Avoid `init()` where possible (`gochecknoinits`).
+- Enums often start at `iota + 1` when zero should mean "unset".
+- Use `time.Time` / `time.Duration`, not raw ints for time.
+- `var _ Interface = (*Impl)(nil)` where useful.
+- Dependency injection over mutable globals. Exit only from `main()`.
+
+### Commits
+
+Never commit or push to git.
+
+## Common pitfalls
+
+- Do not confuse `ChunkSize` (4096 data bytes) with `ChunkWithSpanSize` (4104 including span).
+- XOR distance: XOR between two addresses produces smaller integers as more prefix bits are shared, do not confuse this with lexicographic ordering of addresses.
+- Goroutines must be stoppable (context cancel, quit channel, etc.).
+- Full node vs light node: reserve and storage incentives are full-node concerns.
+- Postage batches can be unusable (expired, depleted, unsynced); check before relying on stamps.
+g

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md