docs: refresh service and compatibility documentation

[tdewitt]

Preface

This was not requested and there's no bug open. I found myself staring at docs and hit a couple snags. I decided to set a robot on it, to try to do a review of the docs against the current state of the code, using the current AGENTS.md as the standard. If this isn't useful, I have no problem just closing but I wanted to see the results and let greptile give it a pass.

Summary

• Refresh the README architecture, service inventory, and feature descriptions to match current main.
• Document STS, current GCS capabilities, Docker-backed data planes, and Datastore's supported transports and index behavior.
• Bring configuration, release, Docker, and compatibility-test guidance in line with the checked-in workflows and suites.
• Remove stale test counts, obsolete examples, unsupported claims, and documentation style violations.

Type of change

• Bug fix (fix:)
• New feature (feat:)
• Breaking change (feat!: or fix!:)
• Docs / chore

GCP Compatibility

Documentation only. No wire protocol behavior changes. Claims were cross-checked against the controllers, service implementations, runtime configuration, compatibility suites, and Terraform/OpenTofu provider configuration.

Validation completed:

• ./mvnw test -Dquarkus.http.test-port=0: 971 tests passed
• mkdocs build --strict
• Mermaid architecture diagram render and visual inspection
• Local link, anchor, navigation, YAML, shell-snippet, suite-inventory, and provider-endpoint checks

Checklist

• ./mvnw test passes locally
• New or updated integration test added
• Commit messages follow Conventional Commits

[greptile-apps]

Greptile Summary

Refreshes service, architecture, configuration, compatibility-testing, and contributor documentation to reflect the repository’s current behavior.

• Clarifies transport-specific support, including Datastore gRPC versus HTTP/protobuf capabilities.
• Documents STS, expanded GCS operations, and Docker-backed service data planes.
• Aligns release, TLS, provider-endpoint, and compatibility-suite guidance with checked-in workflows.

Confidence Score: 5/5

The documentation-only changes appear safe to merge, with both previous findings resolved and no new actionable issues introduced since the prior review.

The latest change correctly narrows the custom-endpoint rule to each provider endpoint’s actual contract, while the resolved Datastore documentation now distinguishes gRPC support from HTTP/protobuf-only GQL and aggregation behavior.

Important Files Changed

Filename	Overview
README.md	Refreshes architecture, service inventory, protocol claims, Docker requirements, and release guidance.
AGENTS.md	Replaces stale inventories with source-of-truth guidance and correctly scopes provider custom-endpoint paths.
CONTRIBUTING.md	Adds protocol-evidence and concurrency/storage-invariant guidance for future behavioral changes.
compatibility-tests/README.md	Updates suite inventory, environment variables, Docker execution, TLS behavior, and IaC coverage.
docs/services/datastore.md	Documents Datastore support and limitations by transport.
docs/services/gcs.md	Expands the documented Cloud Storage operation and compatibility surface.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Clients["SDKs, gcloud, IaC tools"] --> API["Shared API listener<br/>HTTP, JSON, XML, gRPC"]
    API --> Services["In-process emulated services"]
    API --> Control["Docker-backed control planes"]
    Services --> Storage["Configured storage backend"]
    Control --> Docker["Docker Engine"]
    Docker --> Planes["Kafka, PostgreSQL, Cloud Run, k3s"]
    Clients --> Planes

Loading

_{Reviews (4): Last reviewed commit: "docs: scope provider endpoint guidance" | Re-trigger Greptile}

[tdewitt]

@hectorvent This shows as waiting on me but I'm not seeing anything that is actually still open. Perhaps I'm missing something?