docs: golden path as canonical start (handler → OpenAPI → probes)

Wire README, docs hub, cookbook, and examples around docs/GOLDEN_PATH.md.
golden_path example uses route macros so /docs/openapi.json lists /api/v1/ping.
clippy: multipart parse_multipart_part use ? for optional header boundary.

Author: Tuntii

.gitignore

@@ -36,6 +36,7 @@ answer.md
 !docs/native_openapi.md
 !docs/PRODUCTION_BASELINE.md
 !docs/PRODUCTION_CHECKLIST.md
+!docs/GOLDEN_PATH.md
 !docs/cookbook/src/**/*.md
 tasks.md
 /mcps

CHANGELOG.md

@@ -9,11 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **`golden_path` example** (`crates/rustapi-rs/examples/golden_path.rs`) — minimal production-shaped service with `production_defaults`, health probes, and graceful shutdown.
+- **`docs/GOLDEN_PATH.md`** — canonical handler → OpenAPI → probes → MCP/deploy walkthrough; linked from README, docs hub, cookbook SUMMARY, Getting Started.
+- **`golden_path` example** uses route macros + tags so `/docs/openapi.json` includes `/api/v1/ping` (not only `.route()` wiring).
 
 ### Changed
 
 - **Production Readiness v0.2** ([#200](https://github.com/Tuntii/RustAPI/issues/200)): coverage CI publishes HTML + Cobertura artifacts with job summary; release-drafter publishes drafts on `v*` tags; README links [Production Checklist](docs/PRODUCTION_CHECKLIST.md) in the header.
+- README Quick Start: golden path first; document OpenAPI at `/docs/openapi.json`; prefer macros for OpenAPI registration; `tracing-subscriber` + `production_defaults` in the hello snippet.
 - Dependency updates: `actions/checkout@v7`, `actions/cache@v6`, `brotli` 8, `rcgen` 0.14, `tera` 2, `thiserror` 2, OpenTelemetry 0.32 stack, `sqlx` 0.9, `tracing-opentelemetry` 0.33.
 - Default `rustapi-rs` dependency tree slimmed from ~259 to ~158 transitive crates by removing always-on `tracing-subscriber` and gating `rust-i18n` behind the `i18n` feature (English fallbacks by default).
 - `RustApi::new()` no longer auto-initializes `tracing-subscriber`; initialize tracing in `main` (CLI templates already do).

README.md

@@ -9,6 +9,7 @@
   <br />
 
   <a href="https://rustapi.cloud"><strong>Website</strong></a> ·
+  <a href="docs/GOLDEN_PATH.md"><strong>Golden Path</strong></a> ·
   <a href="docs/cookbook/src/SUMMARY.md"><strong>Cookbook</strong></a> ·
   <a href="docs/PRODUCTION_CHECKLIST.md"><strong>Production Checklist</strong></a> ·
   <a href="docs/cookbook/src/recipes/rustapi_cloud.md"><strong>Deploy to Cloud</strong></a> ·
@@ -38,6 +39,22 @@
 
 ---
 
+## Golden Path (start here)
+
+**Handler → OpenAPI (`/docs`) → production probes → (optional) MCP / deploy.**
+
+```bash
+cargo run -p rustapi-rs --example golden_path
+# curl http://127.0.0.1:8080/api/v1/ping
+# open http://127.0.0.1:8080/docs
+```
+
+Full walkthrough: **[docs/GOLDEN_PATH.md](docs/GOLDEN_PATH.md)** · example: [`golden_path.rs`](crates/rustapi-rs/examples/golden_path.rs)
+
+Everything else (JWT, jobs, WS, full extras) branches off this path.
+
+---
+
 ## Overview
 
 RustAPI is a Rust web framework built on **hyper 1.x** and **tokio**, designed for minimal boilerplate while retaining full control over performance. It uses a **facade architecture** (`rustapi-rs`) that shields user code from internal crate changes, keeping the public API stable as internals evolve.
@@ -190,11 +207,15 @@ Current benchmark methodology and canonical published performance claims live in
 
 ## Quick Start
 
-**Recommended usage** (short and clean macro paths):
+Prefer the **[Golden Path](docs/GOLDEN_PATH.md)** for the recommended service shape (`production_defaults` + probes + OpenAPI). Minimal hello:
+
+**Recommended usage** (short macro paths via crate alias):
 
 ```toml
 [dependencies]
 api = { package = "rustapi-rs", version = "0.1.551" }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 ```
 
 ```rust
@@ -208,13 +229,19 @@ async fn hello(Path(name): Path<String>) -> Json<Message> {
     Json(Message { text: format!("Hello, {}!", name) })
 }
 
-#[api::main]
+#[tokio::main]
 async fn main() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
-  RustApi::auto().run("127.0.0.1:8080").await
+    tracing_subscriber::fmt::init();
+    RustApi::auto()
+        .production_defaults("hello")
+        .run("127.0.0.1:8080")
+        .await
 }
 ```
 
-`RustApi::auto()` collects all macro-annotated handlers, generates OpenAPI documentation (served at `/docs`), and starts a multi-threaded tokio runtime.
+`RustApi::auto()` collects macro-annotated handlers, serves Swagger UI at `/docs`, OpenAPI at `/docs/openapi.json`, and starts a multi-threaded tokio runtime. Spec path is **`/docs/openapi.json`** (not `/openapi.json`).
+
+Use **route macros** (`#[api::get]`) so OpenAPI includes your paths. Plain `.route(...)` alone does not register operations in the spec.
 
 ### MCP in 3 lines
 
@@ -223,48 +250,11 @@ let mcp = McpServer::from_rustapi(&app, McpConfig::new().allowed_tags(["public"]
 run_rustapi_and_mcp_with_shutdown(app, "0.0.0.0:8080", mcp, "0.0.0.0:9090", tokio::signal::ctrl_c()).await?;
 ```
 
-Every tagged endpoint becomes an AI agent tool instantly.
+Tag handlers with `#[api::tag("public")]` (or `"agent"`) so only intentional routes become tools. Example: `mcp_tools`.
 
-> **Tip:** Alias the crate as `api` (or `myapi`, `server`, etc.) for clean `#[api::get]` / `#[api::main]` macros — similar to FastAPI's import style.
-
-For production deployments, you can enable standard probe endpoints without writing handlers manually:
-
-```rust
-use api::prelude::*;
-
-#[api::main]
-async fn main() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
-    let health = HealthCheckBuilder::new(true)
-        .add_check("database", || async { HealthStatus::healthy() })
-        .build();
-
-    RustApi::auto()
-        .with_health_check(health)
-        .run("127.0.0.1:8080")
-        .await
-}
-```
-
-This registers:
-- `/health` — aggregate dependency health
-- `/ready` — readiness probe (`503` when dependencies are unhealthy)
-- `/live` — lightweight liveness probe
-
-Or use a single production baseline preset:
-
-```rust
-use api::prelude::*;
-
-#[api::main]
-async fn main() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
-  RustApi::auto()
-    .production_defaults("users-api")
-    .run("127.0.0.1:8080")
-    .await
-}
-```
+> **Tip:** Alias the crate as `api` for clean `#[api::get]` macros.
 
-`production_defaults()` enables request IDs, tracing spans, and standard probe endpoints in one call.
+`production_defaults(name)` enables request IDs, tracing spans, and `/live` `/ready` `/health` in one call. Details: [Production Baseline](docs/PRODUCTION_BASELINE.md).
 
 ## Feature Flags
 
@@ -307,6 +297,7 @@ See [CHANGELOG.md](CHANGELOG.md) for full history. Highlights in **v0.1.551**:
 
 | Resource | Link |
 |----------|------|
+| **Golden Path** | [docs/GOLDEN_PATH.md](docs/GOLDEN_PATH.md) |
 | Docs hub | [docs/README.md](docs/README.md) |
 | Cookbook | [docs/cookbook/src/SUMMARY.md](docs/cookbook/src/SUMMARY.md) |
 | Getting started | [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) |
@@ -316,7 +307,7 @@ See [CHANGELOG.md](CHANGELOG.md) for full history. Highlights in **v0.1.551**:
 | Community & contributing | [docs/COMMUNITY.md](docs/COMMUNITY.md) |
 | API reference | [docs.rs/rustapi-rs](https://docs.rs/rustapi-rs) |
 
-**Examples:** start with [`golden_path`](crates/rustapi-rs/examples/golden_path.rs) (`cargo run -p rustapi-rs --example golden_path`), then browse [`crates/rustapi-rs/examples/`](crates/rustapi-rs/examples/) and **[rustapi-rs-examples](https://github.com/Tuntii/rustapi-rs-examples)**.
+**Examples:** [`golden_path`](crates/rustapi-rs/examples/golden_path.rs) first, then [`crates/rustapi-rs/examples/`](crates/rustapi-rs/examples/) and **[rustapi-rs-examples](https://github.com/Tuntii/rustapi-rs-examples)**.
 
 ## Community & Contributing
 

crates/rustapi-core/src/multipart.rs

@@ -584,10 +584,9 @@ fn trim_trailing_crlf(mut data: Vec<u8>) -> Vec<u8> {
 fn parse_multipart_part(part: &[u8]) -> Option<MultipartField> {
     let (header_end, body_start) = if let Some(pos) = find_subsequence(part, b"\r\n\r\n", 0) {
         (pos, pos + 4)
-    } else if let Some(pos) = find_subsequence(part, b"\n\n", 0) {
-        (pos, pos + 2)
     } else {
-        return None;
+        let pos = find_subsequence(part, b"\n\n", 0)?;
+        (pos, pos + 2)
     };
 
     let headers_section = String::from_utf8_lossy(&part[..header_end]);

crates/rustapi-rs/examples/README.md

@@ -1,11 +1,28 @@
 # RustAPI Examples
 
-This directory contains the in-repository examples for the `rustapi-rs` facade crate.
+In-repository examples for the `rustapi-rs` facade crate.
+
+## Start here: `golden_path`
+
+Minimal production-shaped service: macro route + `Schema`, OpenAPI/Swagger, `production_defaults` probes, graceful shutdown.
+
+```sh
+cargo run -p rustapi-rs --example golden_path
+```
+
+Then:
+
+- `GET http://127.0.0.1:8080/api/v1/ping` → `{"status":"ok"}`
+- `GET http://127.0.0.1:8080/live` (and `/ready`, `/health`)
+- Browser: `http://127.0.0.1:8080/docs` · spec: `/docs/openapi.json`
+
+Guide: [docs/GOLDEN_PATH.md](../../../docs/GOLDEN_PATH.md)
 
 ## Available examples
 
 ### `file_upload`
 
+
 Multipart file upload with `Multipart`, body limits, and safe filename handling.
 
 Run it with:

crates/rustapi-rs/examples/golden_path.rs

@@ -1,17 +1,26 @@
-//! Golden-path production baseline — the smallest service shape we recommend.
+//! Golden path — smallest service shape we recommend shipping.
 //!
-//! Run:
+//! Story in one command:
+//! 1. handler + `Schema` → typed JSON
+//! 2. `RustApi::auto()` → OpenAPI + Swagger UI at `/docs`
+//! 3. `production_defaults` → request IDs, tracing, `/live` `/ready` `/health`
+//! 4. graceful shutdown on Ctrl-C
+//!
+//! Run (from repo root):
 //! ```bash
 //! cargo run -p rustapi-rs --example golden_path
 //! ```
 //!
 //! Verify:
-//! - `GET http://127.0.0.1:8080/live`   → 200
-//! - `GET http://127.0.0.1:8080/ready`  → 200
-//! - `GET http://127.0.0.1:8080/health` → 200
-//! - `GET http://127.0.0.1:8080/api/v1/ping` → `{"status":"ok"}`
+//! ```bash
+//! curl -s http://127.0.0.1:8080/api/v1/ping
+//! curl -s http://127.0.0.1:8080/live
+//! curl -s http://127.0.0.1:8080/docs/openapi.json | head
+//! # browser: http://127.0.0.1:8080/docs
+//! ```
 //!
-//! See [Production Checklist](../../../docs/PRODUCTION_CHECKLIST.md) before real traffic.
+//! Guide: [docs/GOLDEN_PATH.md](../../../docs/GOLDEN_PATH.md)
+//! Before real traffic: [Production Checklist](../../../docs/PRODUCTION_CHECKLIST.md)
 
 use rustapi_rs::prelude::*;
 use tokio::signal;
@@ -21,6 +30,10 @@ struct PingResponse {
     status: &'static str,
 }
 
+/// Liveness-style app check. Probes come from `production_defaults`.
+#[rustapi_rs::get("/api/v1/ping")]
+#[rustapi_rs::tag("public")]
+#[rustapi_rs::summary("Ping - golden path app check")]
 async fn ping() -> Json<PingResponse> {
     Json(PingResponse { status: "ok" })
 }
@@ -34,7 +47,6 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         .on_shutdown(|| async {
             tracing::info!("graceful shutdown complete");
         })
-        .route("/api/v1/ping", get(ping))
         .run_with_shutdown("127.0.0.1:8080", async {
             signal::ctrl_c().await.ok();
         })

docs/GETTING_STARTED.md

@@ -2,6 +2,15 @@
 
 > Build your first API in under 5 minutes.
 
+**Canonical story:** [Golden Path](GOLDEN_PATH.md) — handler → OpenAPI → `production_defaults` → optional MCP/deploy.
+
+In-repo demo:
+
+```bash
+cargo run -p rustapi-rs --example golden_path
+# http://127.0.0.1:8080/docs  ·  /docs/openapi.json  ·  GET /api/v1/ping
+```
+
 ---
 
 ## Prerequisites