chore: update docs

Author: washanhanzi

README.md

@@ -33,12 +33,12 @@ This project includes [Claude Code skills](https://docs.anthropic.com/en/docs/cl
 | Skill | Description |
 |-------|-------------|
 | `submit-issue` | Report bugs, request features, or ask questions |
+| `resolve-issue` | Investigate and resolve GitHub issues |
 | `test` | Run the full test suite |
-| `compare-repo` | Compare an external GitHub repository against connectrpc-axum |
 
 ### Architecture
 
-See [`.claude/architecture.md`](.claude/architecture.md) for detailed documentation on the project structure, core modules, and design decisions.
+See [`.claude/architecture.md`](./docs/guide/architecture.md) for detailed documentation on the project structure, core modules, and design decisions.
 
 ## Examples
 

docs/guide/architecture.md

@@ -157,6 +157,7 @@ These are the types you interact with when building services:
 | `CompressionContext` | Per-request compression context with envelope settings and full `CompressionConfig` |
 | `CompressionEncoding` | Supported encodings: `Gzip`, `Deflate`, `Brotli`, `Zstd`, or `Identity`. Use `codec_with_level()` for level-aware compression |
 | `CompressionLevel` | Compression level (re-exported from tower-http) |
+| `IdempotencyLevel` | Method idempotency: `Unknown`, `NoSideEffects` (enables GET), `Idempotent` |
 | `EnvelopeCompression` | Per-envelope compression settings for streaming RPCs |
 | `ContextError` | Error type for context building failures (protocol detection, header parsing) |
 | `BoxedCodec` | Type-erased codec storage (`Box<dyn Codec>`) for dynamic compression dispatch |
@@ -208,6 +209,8 @@ Two functions create method routers from handlers:
 | `post_connect(f)` | POST | Unary and streaming RPCs |
 | `get_connect(f)` | GET | Idempotent unary RPCs (query param encoding) |
 
+For methods marked with `option idempotency_level = NO_SIDE_EFFECTS` in proto, the code generator automatically merges `get_connect()` and `post_connect()` handlers, enabling both HTTP GET and POST requests per the Connect protocol spec.
+
 ### How Handler Wrappers Work
 
 `ConnectHandlerWrapper<F>` is a newtype that wraps a user function `F`. It has multiple `impl Handler<T, S>` blocks, each with different `where` bounds on `F`. The compiler selects the appropriate impl based on the handler signature.
@@ -341,7 +344,7 @@ For generated code to provide default "unimplemented" methods:
 
 | Module | Purpose |
 |--------|---------|
-| `protocol.rs` | `RequestProtocol` enum, detection, and validation functions (`can_handle_content_type`, `can_handle_get_encoding`, `SUPPORTED_CONTENT_TYPES`) |
+| `protocol.rs` | `RequestProtocol` enum, `IdempotencyLevel` enum, detection, and validation functions (`can_handle_content_type`, `can_handle_get_encoding`, `SUPPORTED_CONTENT_TYPES`) |
 | `envelope_compression.rs` | `Codec` trait, per-envelope compression, `CompressionEncoding::codec_with_level()` for level-aware codecs |
 | `limit.rs` | Receive and send message size limits |
 | `timeout.rs` | Request timeout handling |
@@ -408,7 +411,7 @@ Method availability is enforced via trait bounds:
 
 **Constraints:** `no_handlers()` and `with_tonic()` cannot be combined (enforced at compile time).
 
-**Protoc Fetching:** The `fetch_protoc(version, path)` method downloads a protoc binary to the specified path using the protoc-fetcher crate. This is useful for CI environments or when a system protoc is unavailable.
+**Protoc Fetching:** The `fetch_protoc(version, path)` method downloads a protoc binary to the specified path using the protoc-fetcher crate. This requires the `fetch-protoc` feature flag. Useful for CI environments or when a system protoc is unavailable.
 
 ### Pass 1: Prost + Connect
 
@@ -423,6 +426,9 @@ prost_build::Config
 - User configuration via `with_prost_config()` is applied here
 - All type customization (attributes, extern paths) must be done in this pass
 - Generated builders use the unified `post_connect()` function which auto-detects RPC type from handler signature
+- For methods with `idempotency_level = NO_SIDE_EFFECTS`, the generator merges `get_connect()` and `post_connect()` handlers
+- Generated builders expose `{METHOD}_IDEMPOTENCY` constants for each method's idempotency level
+- `build_connect()` convenience method wraps the router with `MakeServiceBuilder::new()`, providing default gzip compression
 - With `no_handlers()`, only message types are generated (no service builders)
 - Streaming type aliases (`BoxedCall`, `BoxedStreamCall`, etc.) are only generated for RPC patterns actually used by the service
 

docs/guide/axum-router.md

@@ -89,7 +89,34 @@ This serves:
 
 ### GET Requests
 
-Use `get_connect` for idempotent RPCs to enable browser caching:
+#### Automatic GET Support (Recommended)
+
+Mark methods with `idempotency_level = NO_SIDE_EFFECTS` in your proto file to automatically enable GET requests:
+
+```protobuf
+rpc GetUser(GetUserRequest) returns (GetUserResponse) {
+  option idempotency_level = NO_SIDE_EFFECTS;
+}
+```
+
+The generated service builder will automatically handle both GET and POST requests:
+
+```rust
+let router = userservice::UserServiceBuilder::new()
+    .get_user(get_user)
+    .build_connect();  // GET + POST automatically enabled for GetUser
+```
+
+The code generator also exports idempotency level constants for each method:
+
+```rust
+use your_crate::userservice::GET_USER_IDEMPOTENCY;
+// GET_USER_IDEMPOTENCY == IdempotencyLevel::NoSideEffects
+```
+
+#### Manual GET Support
+
+For custom routing, use `get_connect` and `post_connect`:
 
 ```rust
 use axum::Router;
@@ -100,6 +127,8 @@ let router = Router::new()
         get_connect(get_user).merge(post_connect(get_user)));
 ```
 
+#### GET Request Format
+
 GET requests encode the message in query parameters:
 
 | Parameter | Required | Description |

docs/guide/build.md

@@ -15,6 +15,15 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 Use `.fetch_protoc()` to automatically download the protoc compiler. This is useful when you don't want to require protoc to be installed on the build machine.
 
+::: warning Feature Required
+The `fetch_protoc()` method requires the `fetch-protoc` feature flag:
+
+```toml
+[build-dependencies]
+connectrpc-axum-build = { version = "*", features = ["fetch-protoc"] }
+```
+:::
+
 ```rust
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     connectrpc_axum_build::compile_dir("proto")

docs/guide/compression.md

@@ -1,8 +1,22 @@
 # Compression
 
-## Basic Usage
+## Default Compression
 
-Configure response compression using `MakeServiceBuilder`:
+When using `build_connect()` on a service builder, gzip compression is enabled by default:
+
+```rust
+let router = helloworldservice::HelloWorldServiceBuilder::new()
+    .say_hello(say_hello)
+    .build_connect();  // Includes default gzip compression
+```
+
+This uses `MakeServiceBuilder::new()` internally, which provides:
+- Default gzip compression and decompression
+- Standard ConnectLayer configuration
+
+## Custom Configuration
+
+For custom compression settings, use `MakeServiceBuilder` directly:
 
 ```rust
 use connectrpc_axum::{MakeServiceBuilder, CompressionConfig, CompressionLevel};

docs/guide/examples.md

@@ -11,6 +11,7 @@ See the [connectrpc-axum-examples](https://github.com/washanhanzi/connectrpc-axu
 | `connect-client-stream` | Pure Connect client streaming |
 | `connect-bidi-stream` | Pure Connect bidirectional streaming |
 | `get-request` | GET request support for idempotent unary RPCs |
+| `idempotency-get` | Automatic GET support via proto `idempotency_level = NO_SIDE_EFFECTS` |
 
 ## Tonic/gRPC Integration