refactor: organize runtime code into internal packages

.github/workflows/ci.yml

@@ -25,4 +25,4 @@ jobs:
       - name: Test
         run: go test ./...
       - name: Build
-        run: go build -o /tmp/agent-runtime-foundry .
+        run: go build -o /tmp/agent-runtime-foundry ./cmd/agent-runtime-foundry

Dockerfile

@@ -4,7 +4,7 @@ WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
-RUN mkdir -p /out && CGO_ENABLED=0 GOOS=linux go build -o /out/agent-runtime-foundry .
+RUN mkdir -p /out && CGO_ENABLED=0 GOOS=linux go build -o /out/agent-runtime-foundry ./cmd/agent-runtime-foundry
 
 FROM gcr.io/distroless/static:nonroot
 COPY --from=build /out/agent-runtime-foundry /agent-runtime-foundry

Dockerfile.acp

@@ -7,7 +7,7 @@ COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
-    go build -buildvcs=false -trimpath -ldflags='-s -w' -o /out/agent-runtime-foundry .
+    go build -buildvcs=false -trimpath -ldflags='-s -w' -o /out/agent-runtime-foundry ./cmd/agent-runtime-foundry
 ARG FOUNDRY_CONFIG=examples/foundry-acp.json
 COPY ${FOUNDRY_CONFIG} /out/rootfs/agent/foundry.json
 RUN chmod 0555 /out/rootfs/agent && chmod 0444 /out/rootfs/agent/foundry.json

Makefile

@@ -11,7 +11,7 @@ test:
 
 build:
 	mkdir -p bin
-	go build -o bin/agent-runtime-foundry .
+	go build -o bin/agent-runtime-foundry ./cmd/agent-runtime-foundry
 
 verify: vet test build
 	@test -z "$$(gofmt -l .)"

README.md

@@ -166,6 +166,28 @@ make build
 docker build -t ghcr.io/orka-agents/agent-runtime-foundry:latest .
 ```
 
+## Code layout
+
+The binary entry point is in `cmd/agent-runtime-foundry`. The default mode serves
+harness v1 HTTP. Use `--protocol` to select `acp`, `broker`, `hosted`, or
+`hosted-gateway`.
+
+| Directory | Responsibility |
+| --- | --- |
+| `internal/adapter` | Harness v1 HTTP server, turn lifecycle, and Responses client. |
+| `internal/acp` | ACP child process, prompt execution, and loopback MCP client. |
+| `internal/broker` | Durable Foundry session ownership and response settlement. |
+| `internal/hosted` | Hosted supervisor, Kubernetes gateway, and relay transport. |
+| `internal/foundry` | Shared agent configuration, Azure authentication, Responses parsing, and validation. |
+| `internal/brokerapi` | Broker routes shared with the hosted gateway. |
+| `internal/strictjson` | Duplicate-field and Unicode validation for JSON envelopes. |
+| `internal/durablestore` | Private files, lock ownership, and directory durability. |
+| `internal/harness`, `internal/events`, `internal/redact` | Harness contract and redaction helpers. |
+| `conformance` | Harness v1 conformance probes. |
+
+Tests live beside the implementation they exercise. The broker and hosted store
+tests share initialization checks in `internal/durablestore/storetest`.
+
 ## Orka facade
 
 Deploy this adapter and its Kubernetes `Service` separately, then point an Orka