diff --git a/README.md b/README.md
index d7de7bd..7614c3c 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,80 @@
-# proto-go
+# GitCaddy Actions Proto
 
+Protocol buffer definitions for communication between Gitea Actions runners and the Gitea server.
+
+> **This is a GitCaddy fork** of [code.gitea.io/actions-proto-go](https://gitea.com/gitea/actions-proto-go) with enhanced capability reporting support.
+
+## Overview
+
+This package provides the protobuf-generated Go code for the Gitea Actions runner protocol. It defines the RPC services and message types used for:
+
+- Runner registration and declaration
+- Task fetching and execution
+- Log streaming and status updates
+- **Runner capability reporting** (GitCaddy enhancement)
+
+## Installation
+
+```bash
+go get git.marketally.com/gitcaddy/actions-proto-go
+```
+
+## GitCaddy Enhancements
+
+### Runner Capability Reporting
+
+This fork adds the `CapabilitiesJson` field to the `DeclareRequest` message, enabling runners to report their capabilities to the Gitea server:
+
+```protobuf
+message DeclareRequest {
+  string version = 1;
+  repeated string labels = 2;
+  string capabilities_json = 3;  // NEW: JSON-encoded runner capabilities
+}
+```
+
+The capabilities JSON includes:
+- **OS and Architecture**: Runtime environment details
+- **Docker Support**: Whether Docker/Podman is available
+- **Shell Support**: Available shells (bash, sh, powershell, etc.)
+- **Tool Versions**: Installed tools like Node.js, Go, Python, etc.
+- **Feature Flags**: Cache support, artifact handling, etc.
+- **Limitations**: Known constraints for AI workflow generation
+
+### Why This Matters
+
+AI tools generating CI/CD workflows can query the Gitea API to discover runner capabilities *before* writing workflows, reducing trial-and-error iterations.
+
+## Usage
+
+```go
+import (
+    runnerv1 "git.marketally.com/gitcaddy/actions-proto-go/runner/v1"
+    "git.marketally.com/gitcaddy/actions-proto-go/runner/v1/runnerv1connect"
+)
+
+// Create a client
+client := runnerv1connect.NewRunnerServiceClient(httpClient, serverURL)
+
+// Declare runner with capabilities
+resp, err := client.Declare(ctx, connect.NewRequest(&runnerv1.DeclareRequest{
+    Version:          "0.3.1",
+    Labels:           []string{"ubuntu-latest", "docker"},
+    CapabilitiesJson: `{"os":"linux","arch":"amd64","docker":true}`,
+}))
+```
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [gitcaddy/gitea](https://git.marketally.com/gitcaddy/gitea) | GitCaddy Gitea fork with AI-friendly enhancements |
+| [gitcaddy/act_runner](https://git.marketally.com/gitcaddy/act_runner) | Runner with capability detection |
+
+## Upstream
+
+This project is a fork of [code.gitea.io/actions-proto-go](https://gitea.com/gitea/actions-proto-go). We aim to contribute enhancements back to upstream where appropriate.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.