docs: refresh AGENTS.md layout and add stderr debugging gotcha #5

Merged

w33ble merged 1 commit from chore/agents-md-refresh into main

2026-09-29 12:18:31 -06:00

hijynx commented

2026-09-29 12:18:16 -06:00

Collaborator

Summary

Layout section now lists the actual flat files (proxy.go, transport.go, reconnect.go, heartbeat.go) instead of the stale internal/ split that never happened.
SDK gotchas: debug a hanging bridge by running the binary directly with piped stdin and --debug, since MCP clients swallow child stderr.

Why

Retrospective findings from debugging the pit hang: the stale layout pointer and the missing stderr-visibility gotcha both slowed diagnosis.

Verification

go build ./..., go vet ./..., golangci-lint run (0 issues), go test ./... all pass. Docs-only change.

## Summary - Layout section now lists the actual flat files (`proxy.go`, `transport.go`, `reconnect.go`, `heartbeat.go`) instead of the stale `internal/` split that never happened. - SDK gotchas: debug a hanging bridge by running the binary directly with piped stdin and `--debug`, since MCP clients swallow child stderr. ## Why Retrospective findings from debugging the pit hang: the stale layout pointer and the missing stderr-visibility gotcha both slowed diagnosis. ## Verification `go build ./...`, `go vet ./...`, `golangci-lint run` (0 issues), `go test ./...` all pass. Docs-only change.

hijynx added 1 commit

2026-09-29 12:18:16 -06:00