From 87984f76530163d2746cdadb2b4c110b79c4527d Mon Sep 17 00:00:00 2001
From: RA <70325462+RAprogramm@users.noreply.github.com>
Date: Wed, 24 Sep 2025 12:46:36 +0700
Subject: [PATCH] docs: rewrite README for 0.20 workspace

---
 CHANGELOG.md       |   5 +
 Cargo.lock         |   2 +-
 Cargo.toml         |   2 +-
 README.md          | 577 +++++++--------------------------------------
 README.ru.md       | 498 ++++++++++++++++----------------------
 README.template.md | 540 ++++++------------------------------------
 6 files changed, 364 insertions(+), 1260 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf24aca..16e02c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.20.5] - 2025-10-05
+
+### Changed
+- Rewrote the English and Russian READMEs to reflect the matured workspace, feature flags, telemetry flows and transport integrations introduced across the 0.20 releases.
+
 ## [0.20.4] - 2025-10-04
 
 ### Added
diff --git a/Cargo.lock b/Cargo.lock
index 92e21e8..d6d73a1 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1727,7 +1727,7 @@ dependencies = [
 
 [[package]]
 name = "masterror"
-version = "0.20.4"
+version = "0.20.5"
 dependencies = [
  "actix-web",
  "axum 0.8.4",
diff --git a/Cargo.toml b/Cargo.toml
index 641a46b..9fd4521 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "masterror"
-version = "0.20.4"
+version = "0.20.5"
 rust-version = "1.90"
 edition = "2024"
 license = "MIT OR Apache-2.0"
diff --git a/README.md b/README.md
index 9cbec41..13d327c 100644
--- a/README.md
+++ b/README.md
@@ -14,33 +14,66 @@
 
 > 🇷🇺 Читайте README на [русском языке](README.ru.md).
 
-Small, pragmatic error model for API-heavy Rust services with native derives
-and typed telemetry.
-Core is framework-agnostic; integrations are opt-in via feature flags.
-Stable categories, conservative HTTP mapping, no `unsafe`.
-
-- Core types: `AppError`, `AppErrorKind`, `AppResult`, `AppCode`, `ProblemJson`, `ErrorResponse`, `Metadata`
-- Derive macros: `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]`,
-  `#[masterror(...)]`, `#[provide]` for domain mappings and structured
-  telemetry
-- Optional Axum/Actix integration and browser/WASM console logging
-- Optional OpenAPI schema (via `utoipa`)
-- Structured metadata helpers via `field::*` builders
-- Conversions from `sqlx`, `reqwest`, `redis`, `validator`, `config`, `tokio`
-- Turnkey domain taxonomy and helpers (`turnkey` feature)
-
-👉 Explore the new [error-handling wiki](docs/wiki/index.md) for step-by-step
-guides, comparisons with `thiserror`/`anyhow`, and troubleshooting recipes.
-
----
+`masterror` grew from a handful of helpers into a workspace of composable crates for
+building consistent, observable error surfaces across Rust services. The core
+crate stays framework-agnostic, while feature flags light up transport adapters,
+integrations and telemetry without pulling in heavyweight defaults. No
+`unsafe`, MSRV is pinned, and the derive macros keep your domain types in charge
+of redaction and metadata.
+
+### Highlights
+
+- **Unified taxonomy.** `AppError`, `AppErrorKind` and `AppCode` model domain and
+  transport concerns with conservative HTTP/gRPC mappings, turnkey retry/auth
+  hints and RFC7807 output via `ProblemJson`.
+- **Native derives.** `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]`,
+  `#[masterror(...)]` and `#[provide]` wire custom types into `AppError` while
+  forwarding sources, backtraces, telemetry providers and redaction policy.
+- **Typed telemetry.** `Metadata` stores structured key/value context with
+  per-field redaction controls and builders in `field::*`, so logs stay
+  structured without manual `String` maps.
+- **Transport adapters.** Optional features expose Actix/Axum responders,
+  `tonic::Status` conversions, WASM/browser logging and OpenAPI schema
+  generation without contaminating the lean default build.
+- **Battle-tested integrations.** Enable focused mappings for `sqlx`,
+  `reqwest`, `redis`, `validator`, `config`, `tokio`, `teloxide`, `multipart`,
+  Telegram WebApp SDK and more — each translating library errors into the
+  taxonomy with telemetry attached.
+- **Turnkey defaults.** The `turnkey` module ships a ready-to-use error catalog,
+  helper builders and tracing instrumentation for teams that want a consistent
+  baseline out of the box.
+
+### Workspace crates
+
+| Crate | What it provides | When to depend on it |
+| --- | --- | --- |
+| [`masterror`](https://crates.io/crates/masterror) | Core error types, metadata builders, transports, integrations and the prelude. | Application crates, services and libraries that want a stable error surface. |
+| [`masterror-derive`](masterror-derive/README.md) | Proc-macros backing `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]` and `#[provide]`. | Brought in automatically via `masterror`; depend directly only for macro hacking. |
+| [`masterror-template`](masterror-template/README.md) | Shared template parser used by the derive macros for formatter analysis. | Internal dependency; reuse when you need the template parser elsewhere. |
+
+### Feature flags at a glance
+
+Pick only what you need; everything is off by default.
+
+- **Web transports:** `axum`, `actix`, `multipart`, `openapi`, `serde_json`.
+- **Telemetry & observability:** `tracing`, `metrics`, `backtrace`.
+- **Async & IO integrations:** `tokio`, `reqwest`, `sqlx`, `sqlx-migrate`,
+  `redis`, `validator`, `config`.
+- **Messaging & bots:** `teloxide`, `telegram-webapp-sdk`.
+- **Front-end tooling:** `frontend` for WASM/browser console logging.
+- **gRPC:** `tonic` to emit `tonic::Status` responses.
+- **Batteries included:** `turnkey` to adopt the pre-built taxonomy and helpers.
+
+The build script keeps the full feature snippet below in sync with
+`Cargo.toml`.
 
 ### TL;DR
 
 ~~~toml
 [dependencies]
-masterror = { version = "0.20.4", default-features = false }
+masterror = { version = "0.20.5", default-features = false }
 # or with features:
-# masterror = { version = "0.20.4", features = [
+# masterror = { version = "0.20.5", features = [
 #   "axum", "actix", "openapi", "serde_json",
 #   "tracing", "metrics", "backtrace", "sqlx",
 #   "sqlx-migrate", "reqwest", "redis", "validator",
@@ -49,52 +82,8 @@ masterror = { version = "0.20.4", default-features = false }
 # ] }
 ~~~
 
-*Since v0.5.0: derive custom errors via `#[derive(Error)]` (`use masterror::Error;`) and inspect browser logging failures with `BrowserConsoleError::context()`.*
-*Since v0.4.0: optional `frontend` feature for WASM/browser console logging.*
-*Since v0.3.0: stable `AppCode` enum and extended `ErrorResponse` with retry/authentication metadata.*
-*Since v0.15.0: RFC7807 `ProblemJson` responses for HTTP integrations and `tonic::Status` conversion.*
-
 ---
 
-<details>
-  <summary><b>Why this crate?</b></summary>
-
-- **Stable taxonomy.** Small set of `AppErrorKind` categories mapping conservatively to HTTP.
-- **Framework-agnostic.** No assumptions, no `unsafe`, MSRV pinned.
-- **Opt-in integrations.** Zero default features; you enable what you need.
-- **Clean wire contract.** `ProblemJson { type?, title, status, detail?, code, grpc?, metadata? }` with `Retry-After` / `WWW-Authenticate` headers when present.
-- **Typed telemetry.** `Metadata` preserves structured key/value context without `String` maps.
-- **One log at boundary.** Log once with `tracing`.
-- **Less boilerplate.** Built-in conversions, compact prelude, and the
-  native `masterror::Error` derive with `#[from]` / `#[error(transparent)]`
-  support.
-- **Consistent workspace.** Same error surface across crates.
-
-</details>
-
-<details>
-  <summary><b>Installation</b></summary>
-
-~~~toml
-[dependencies]
-# lean core
-masterror = { version = "0.20.4", default-features = false }
-
-# with Axum/Actix + JSON + integrations
-# masterror = { version = "0.20.4", features = [
-#   "axum", "actix", "openapi", "serde_json",
-#   "tracing", "metrics", "backtrace", "sqlx",
-#   "sqlx-migrate", "reqwest", "redis", "validator",
-#   "config", "tokio", "multipart", "teloxide",
-#   "telegram-webapp-sdk", "tonic", "frontend", "turnkey"
-# ] }
-~~~
-
-**MSRV:** 1.90
-**No unsafe:** forbidden by crate.
-
-</details>
-
 <details>
   <summary><b>Quick start</b></summary>
 
@@ -126,7 +115,10 @@ fn do_work(flag: bool) -> AppResult<()> {
 </details>
 
 <details>
-  <summary><b>Derive custom errors</b></summary>
+  <summary><b>Derive domain errors and map them to transports</b></summary>
+
+`masterror` ships native derives so your domain types stay expressive while the
+crate handles conversions, telemetry and redaction for you.
 
 ~~~rust
 use std::io;
@@ -160,7 +152,7 @@ let wrapped = WrappedDomainError::from(err);
 assert_eq!(wrapped.to_string(), "I/O failed: disk offline");
 ~~~
 
-- `use masterror::Error;` brings the crate's derive macro into scope.
+- `use masterror::Error;` brings the derive macro into scope.
 - `#[from]` automatically implements `From<...>` while ensuring wrapper shapes are
   valid.
 - `#[error(transparent)]` enforces single-field wrappers that forward
@@ -183,12 +175,15 @@ assert_eq!(wrapped.to_string(), "I/O failed: disk offline");
   placeholder, making it easy to branch on the requested rendering behaviour
   without manually matching every enum variant.
 
-#### `#[derive(Masterror)]` and `#[masterror(...)]`
+</details>
+
+<details>
+  <summary><b>Attach telemetry, redaction policy and conversions</b></summary>
 
-`#[derive(Masterror)]` wires a domain error directly into [`masterror::Error`],
-augmenting it with metadata, redaction policy and optional transport mappings.
-The accompanying `#[masterror(...)]` attribute mirrors the `#[app_error]`
-syntax while remaining explicit about telemetry:
+`#[derive(Masterror)]` wires a domain error into [`masterror::Error`], adds
+metadata, redaction policy and optional transport mappings. The accompanying
+`#[masterror(...)]` attribute mirrors the `#[app_error]` syntax while staying
+explicit about telemetry and redaction.
 
 ~~~rust
 use masterror::{
@@ -255,103 +250,10 @@ All familiar field-level attributes (`#[from]`, `#[source]`, `#[backtrace]`)
 are still honoured. Sources and backtraces are automatically attached to the
 generated [`masterror::Error`].
 
-#### Display shorthand projections
-
-`#[error("...")]` supports the same shorthand syntax as `thiserror` for
-referencing fields with `.field` or `.0`. The derive now understands chained
-segments, so projections like `.limits.lo`, `.0.data` or
-`.suggestion.as_ref().map_or_else(...)` keep compiling unchanged. Raw
-identifiers and tuple indices are preserved, ensuring keywords such as
-`r#type` and tuple fields continue to work even when you call methods on the
-projected value.
-
-~~~rust
-use masterror::Error;
-
-#[derive(Debug)]
-struct Limits {
-    lo: i32,
-    hi: i32,
-}
-
-#[derive(Debug, Error)]
-#[error(
-    "range {lo}-{hi} suggestion {suggestion}",
-    lo = .limits.lo,
-    hi = .limits.hi,
-    suggestion = .suggestion.as_ref().map_or_else(|| "<none>", |s| s.as_str())
-)]
-struct RangeError {
-    limits: Limits,
-    suggestion: Option<String>,
-}
-
-#[derive(Debug)]
-struct Payload {
-    data: &'static str,
-}
-
-#[derive(Debug, Error)]
-enum UiError {
-    #[error("tuple data {data}", data = .0.data)]
-    Tuple(Payload),
-    #[error(
-        "named suggestion {value}",
-        value = .suggestion.as_ref().map_or_else(|| "<none>", |s| s.as_str())
-    )]
-    Named { suggestion: Option<String> },
-}
-~~~
-
-#### AppError conversions
-
-Annotating structs or enum variants with `#[app_error(...)]` captures the
-metadata required to convert the domain error into `AppError` (and optionally
-`AppCode`). Every variant in an enum must provide the mapping when any variant
-requests it.
-
-~~~rust
-use masterror::{AppCode, AppError, AppErrorKind, Error};
-
-#[derive(Debug, Error)]
-#[error("missing flag: {name}")]
-#[app_error(kind = AppErrorKind::BadRequest, code = AppCode::BadRequest, message)]
-struct MissingFlag {
-    name: &'static str,
-}
-
-let app: AppError = MissingFlag { name: "feature" }.into();
-assert!(matches!(app.kind, AppErrorKind::BadRequest));
-assert_eq!(app.message.as_deref(), Some("missing flag: feature"));
-
-let code: AppCode = MissingFlag { name: "feature" }.into();
-assert!(matches!(code, AppCode::BadRequest));
-~~~
-
-For enums, each variant specifies the mapping while the derive generates a
-single `From<Enum>` implementation that matches every variant:
-
-~~~rust
-#[derive(Debug, Error)]
-enum ApiError {
-    #[error("missing resource {id}")]
-    #[app_error(
-        kind = AppErrorKind::NotFound,
-        code = AppCode::NotFound,
-        message
-    )]
-    Missing { id: u64 },
-    #[error("backend unavailable")]
-    #[app_error(kind = AppErrorKind::Service, code = AppCode::Service)]
-    Backend,
-}
-
-let missing = ApiError::Missing { id: 7 };
-let as_app: AppError = missing.into();
-assert_eq!(as_app.message.as_deref(), Some("missing resource 7"));
-~~~
+</details>
 
-#### Structured telemetry providers and AppError mappings
+<details>
+  <summary><b>Structured telemetry providers and AppError mappings</b></summary>
 
 `#[provide(...)]` exposes typed context through `std::error::Request`, while
 `#[app_error(...)]` records how your domain error translates into `AppError`
@@ -452,173 +354,12 @@ assert!(matches!(app.kind, AppErrorKind::Service));
 
 Compared to `thiserror`, you retain the familiar deriving surface while gaining
 structured telemetry (`#[provide]`) and first-class conversions into
-`AppError`/`AppCode` without writing manual `From` implementations.
-
-#### Formatter traits
-
-Placeholders default to `Display` (`{value}`) but can opt into richer
-formatters via the same specifiers supported by `thiserror` v2.
-`TemplateFormatter::is_alternate()` tracks the `#` flag, while
-`TemplateFormatterKind` exposes the underlying `core::fmt` trait so derived
-code can branch on the requested renderer without manual pattern matching.
-Unsupported formatters surface a compile error that mirrors `thiserror`'s
-diagnostics.
-
-| Specifier        | `core::fmt` trait          | Example output         | Notes |
-|------------------|----------------------------|------------------------|-------|
-| _default_        | `core::fmt::Display`       | `value`                | User-facing strings; `#` has no effect. |
-| `:?` / `:#?`     | `core::fmt::Debug`         | `Struct { .. }` / multi-line | Mirrors `Debug`; `#` pretty-prints structs. |
-| `:x` / `:#x`     | `core::fmt::LowerHex`      | `0x2a`                 | Hexadecimal; `#` prepends `0x`. |
-| `:X` / `:#X`     | `core::fmt::UpperHex`      | `0x2A`                 | Uppercase hex; `#` prepends `0x`. |
-| `:p` / `:#p`     | `core::fmt::Pointer`       | `0x1f00` / `0x1f00`    | Raw pointers; `#` is accepted for compatibility. |
-| `:b` / `:#b`     | `core::fmt::Binary`        | `101010` / `0b101010` | Binary; `#` prepends `0b`. |
-| `:o` / `:#o`     | `core::fmt::Octal`         | `52` / `0o52`         | Octal; `#` prepends `0o`. |
-| `:e` / `:#e`     | `core::fmt::LowerExp`      | `1.5e-2`              | Scientific notation; `#` forces the decimal point. |
-| `:E` / `:#E`     | `core::fmt::UpperExp`      | `1.5E-2`              | Uppercase scientific; `#` forces the decimal point. |
-
-- `TemplateFormatterKind::supports_alternate()` reports whether the `#` flag is
-  meaningful for the requested trait (pointer accepts it even though the output
-  matches the non-alternate form).
-- `TemplateFormatterKind::specifier()` returns the canonical format specifier
-  character when one exists, enabling custom derives to re-render placeholders
-  in their original style.
-- `TemplateFormatter::from_kind(kind, alternate)` reconstructs a formatter from
-  the lightweight `TemplateFormatterKind`, making it easy to toggle the
-  alternate flag in generated code.
-
-~~~rust
-use core::ptr;
-
-use masterror::Error;
-
-#[derive(Debug, Error)]
-#[error(
-    "debug={payload:?}, hex={id:#x}, ptr={ptr:p}, bin={mask:#b}, \
-     oct={mask:o}, lower={ratio:e}, upper={ratio:E}"
-)]
-struct FormattedError {
-    id: u32,
-    payload: String,
-    ptr: *const u8,
-    mask: u8,
-    ratio: f32,
-}
-
-let err = FormattedError {
-    id: 0x2a,
-    payload: "hello".into(),
-    ptr: ptr::null(),
-    mask: 0b1010_0001,
-    ratio: 0.15625,
-};
-
-let rendered = err.to_string();
-assert!(rendered.contains("debug=\"hello\""));
-assert!(rendered.contains("hex=0x2a"));
-assert!(rendered.contains("ptr=0x0"));
-assert!(rendered.contains("bin=0b10100001"));
-assert!(rendered.contains("oct=241"));
-assert!(rendered.contains("lower=1.5625e-1"));
-assert!(rendered.contains("upper=1.5625E-1"));
-~~~
-
-~~~rust
-use masterror::error::template::{
-    ErrorTemplate, TemplateFormatter, TemplateFormatterKind
-};
-
-let template = ErrorTemplate::parse("{code:#x} → {payload:?}").expect("parse");
-let mut placeholders = template.placeholders();
-
-let code = placeholders.next().expect("code placeholder");
-let code_formatter = code.formatter();
-assert!(matches!(
-    code_formatter,
-    TemplateFormatter::LowerHex { alternate: true }
-));
-let code_kind = code_formatter.kind();
-assert_eq!(code_kind, TemplateFormatterKind::LowerHex);
-assert!(code_formatter.is_alternate());
-assert_eq!(code_kind.specifier(), Some('x'));
-assert!(code_kind.supports_alternate());
-let lowered = TemplateFormatter::from_kind(code_kind, false);
-assert!(matches!(
-    lowered,
-    TemplateFormatter::LowerHex { alternate: false }
-));
-
-let payload = placeholders.next().expect("payload placeholder");
-let payload_formatter = payload.formatter();
-assert_eq!(
-    payload_formatter,
-    &TemplateFormatter::Debug { alternate: false }
-);
-let payload_kind = payload_formatter.kind();
-assert_eq!(payload_kind, TemplateFormatterKind::Debug);
-assert_eq!(payload_kind.specifier(), Some('?'));
-assert!(payload_kind.supports_alternate());
-let pretty_debug = TemplateFormatter::from_kind(payload_kind, true);
-assert!(matches!(
-    pretty_debug,
-    TemplateFormatter::Debug { alternate: true }
-));
-assert!(pretty_debug.is_alternate());
-~~~
-
-Display-only format specs (alignment, precision, fill — including `#` as a fill
-character) are preserved so you can forward them to `write!` without rebuilding
-the fragment:
-
-~~~rust
-use masterror::error::template::ErrorTemplate;
-
-let aligned = ErrorTemplate::parse("{value:>8}").expect("parse");
-let display = aligned.placeholders().next().expect("display placeholder");
-assert_eq!(display.formatter().display_spec(), Some(">8"));
-assert_eq!(
-    display
-        .formatter()
-        .format_fragment()
-        .as_deref(),
-    Some(">8")
-);
-
-let hashed = ErrorTemplate::parse("{value:#>4}").expect("parse");
-let hash_placeholder = hashed
-    .placeholders()
-    .next()
-    .expect("hash-fill display placeholder");
-assert_eq!(hash_placeholder.formatter().display_spec(), Some("#>4"));
-assert_eq!(
-    hash_placeholder
-        .formatter()
-        .format_fragment()
-        .as_deref(),
-    Some("#>4")
-);
-~~~
-
-> **Compatibility with `thiserror` v2:** the derive understands the extended
-> formatter set introduced in `thiserror` 2.x and reports identical diagnostics
-> for unsupported specifiers, so migrating existing derives is drop-in.
-
-```rust
-use masterror::error::template::{ErrorTemplate, TemplateIdentifier};
-
-let template = ErrorTemplate::parse("{code}: {message}").expect("parse");
-let display = template.display_with(|placeholder, f| match placeholder.identifier() {
-    TemplateIdentifier::Named("code") => write!(f, "{}", 404),
-    TemplateIdentifier::Named("message") => f.write_str("Not Found"),
-    _ => Ok(()),
-});
-
-assert_eq!(display.to_string(), "404: Not Found");
-```
+`AppError`/`AppCode` without manual glue.
 
 </details>
 
 <details>
-  <summary><b>Error response payload</b></summary>
+  <summary><b>Problem JSON payloads and retry/authentication hints</b></summary>
 
 ~~~rust
 use masterror::{AppError, AppErrorKind, ProblemJson};
@@ -637,172 +378,14 @@ assert_eq!(problem.grpc.expect("grpc").name, "UNAUTHENTICATED");
 
 </details>
 
-<details>
-  <summary><b>Web framework integrations</b></summary>
-
-<details>
-  <summary>Axum</summary>
-
-~~~rust
-// features = ["axum", "serde_json"]
-...
-    assert!(payload.is_object());
-
-    #[cfg(target_arch = "wasm32")]
-    {
-        if let Err(console_err) = err.log_to_browser_console() {
-            eprintln!(
-                "failed to log to browser console: {:?}",
-                console_err.context()
-            );
-        }
-    }
-
-    Ok(())
-}
-~~~
-
-- On non-WASM targets `log_to_browser_console` returns
-  `BrowserConsoleError::UnsupportedTarget`.
-- `BrowserConsoleError::context()` exposes optional browser diagnostics for
-  logging/telemetry when console logging fails.
-
-</details>
-
-</details>
-
-<details>
-  <summary><b>Feature flags</b></summary>
-
-- `axum` — IntoResponse integration with structured JSON bodies
-- `actix` — Actix Web ResponseError and Responder implementations
-- `openapi` — Generate utoipa OpenAPI schema for ErrorResponse
-- `serde_json` — Attach structured JSON details to AppError
-- `tracing` — Emit structured tracing events when errors are constructed
-- `metrics` — Increment `error_total{code,category}` counter for each AppError
-- `backtrace` — Capture lazy `Backtrace` snapshots when telemetry is flushed
-- `sqlx` — Classify sqlx_core::Error variants into AppError kinds
-- `sqlx-migrate` — Map sqlx::migrate::MigrateError into AppError (Database)
-- `reqwest` — Classify reqwest::Error as timeout/network/external API
-- `redis` — Map redis::RedisError into cache-aware AppError
-- `validator` — Convert validator::ValidationErrors into validation failures
-- `config` — Propagate config::ConfigError as configuration issues
-- `tokio` — Classify tokio::time::error::Elapsed as timeout
-- `multipart` — Handle axum multipart extraction errors
-- `teloxide` — Convert teloxide_core::RequestError into domain errors
-- `telegram-webapp-sdk` — Surface Telegram WebApp validation failures
-- `tonic` — Convert AppError into tonic::Status with redaction
-- `frontend` — Log to the browser console and convert to JsValue on WASM
-- `turnkey` — Ship Turnkey-specific error taxonomy and conversions
-
-</details>
-
-<details>
-  <summary><b>Conversions</b></summary>
-
-- `std::io::Error` → Internal
-- `String` → BadRequest
-- `sqlx::Error` → NotFound/Database
-- `redis::RedisError` → Cache
-- `reqwest::Error` → Timeout/Network/ExternalApi
-- `axum::extract::multipart::MultipartError` → BadRequest
-- `validator::ValidationErrors` → Validation
-- `config::ConfigError` → Config
-- `tokio::time::error::Elapsed` → Timeout
-- `teloxide_core::RequestError` → RateLimited/Network/ExternalApi/Deserialization/Internal
-- `telegram_webapp_sdk::utils::validate_init_data::ValidationError` → TelegramAuth
-
-</details>
-
-<details>
-  <summary><b>Typical setups</b></summary>
-
-Minimal core:
-
-~~~toml
-masterror = { version = "0.20.4", default-features = false }
-~~~
-
-API (Axum + JSON + deps):
-
-~~~toml
-masterror = { version = "0.20.4", features = [
-  "axum", "serde_json", "openapi",
-  "sqlx", "reqwest", "redis", "validator", "config", "tokio"
-] }
-~~~
-
-API (Actix + JSON + deps):
-
-~~~toml
-masterror = { version = "0.20.4", features = [
-  "actix", "serde_json", "openapi",
-  "sqlx", "reqwest", "redis", "validator", "config", "tokio"
-] }
-~~~
-
-</details>
-
-<details>
-  <summary><b>Turnkey</b></summary>
-
-~~~rust
-// features = ["turnkey"]
-use masterror::turnkey::{classify_turnkey_error, TurnkeyError, TurnkeyErrorKind};
-use masterror::{AppError, AppErrorKind};
-
-// Classify a raw SDK/provider error
-let kind = classify_turnkey_error("429 Too Many Requests");
-assert!(matches!(kind, TurnkeyErrorKind::RateLimited));
-
-// Wrap into AppError
-let e = TurnkeyError::new(TurnkeyErrorKind::RateLimited, "throttled upstream");
-let app: AppError = e.into();
-assert_eq!(app.kind, AppErrorKind::RateLimited);
-~~~
-
-</details>
-
-<details>
-  <summary><b>Migration 0.2 → 0.3</b></summary>
-
-- Use `ErrorResponse::new(status, AppCode::..., "msg")` instead of legacy
-- New helpers: `.with_retry_after_secs`, `.with_retry_after_duration`, `.with_www_authenticate`
-- `ErrorResponse::new_legacy` is temporary shim
-
-</details>
-
-<details>
-  <summary><b>Versioning & MSRV</b></summary>
+### Further resources
 
-Semantic versioning. Breaking API/wire contract → major bump.
-MSRV = 1.90 (may raise in minor, never in patch).
+- Explore the [error-handling wiki](docs/wiki/index.md) for step-by-step guides,
+  comparisons with `thiserror`/`anyhow`, and troubleshooting recipes.
+- Browse the [crate documentation on docs.rs](https://docs.rs/masterror) for API
+  details, feature-specific guides and transport tables.
+- Check [`CHANGELOG.md`](CHANGELOG.md) for release highlights and migration notes.
 
-</details>
-
-<details>
-  <summary><b>Release checklist</b></summary>
-
-1. `cargo +nightly fmt --`
-1. `cargo clippy -- -D warnings`
-1. `cargo test --all`
-1. `cargo build` (regenerates README.md from the template)
-1. `cargo doc --no-deps`
-1. `cargo package --locked`
-
-</details>
-
-<details>
-  <summary><b>Non-goals</b></summary>
-
-- Not a general-purpose error aggregator like `anyhow`
-- Not a replacement for your domain errors
-
-</details>
-
-<details>
-  <summary><b>License</b></summary>
-
-Apache-2.0 OR MIT, at your option.
+---
 
-</details>
+MSRV: **1.90** · License: **MIT OR Apache-2.0** · No `unsafe`
diff --git a/README.ru.md b/README.ru.md
index d87a385..2c90dfc 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -1,6 +1,6 @@
 # masterror · Каркас-независимые типы ошибок приложений
 
-> Этот документ — русская версия основной документации. Английскую версию см. в [README.md](README.md).
+> Эта страница — русская версия основной документации. Английский оригинал см. в [README.md](README.md).
 
 [![Crates.io](https://img.shields.io/crates/v/masterror)](https://crates.io/crates/masterror)
 [![docs.rs](https://img.shields.io/docsrs/masterror)](https://docs.rs/masterror)
@@ -11,47 +11,74 @@
 [![Security audit](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml/badge.svg?branch=main&label=Security%20audit)](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml?query=branch%3Amain)
 [![Cargo Deny](https://img.shields.io/github/actions/workflow/status/RAprogramm/masterror/ci.yml?branch=main&label=Cargo%20Deny)](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml?query=branch%3Amain)
 
-Небольшая прагматичная модель ошибок для Rust-сервисов с выраженным API и
-встроенными деривами.
-Основной крейт не зависит от веб-фреймворков, а расширения включаются через
-фичи. Таксономия ошибок стабильна, соответствие HTTP-кодам консервативно,
-`unsafe` запрещён.
-
-## Основные возможности
-
-- Базовые типы: `AppError`, `AppErrorKind`, `AppResult`, `AppCode`, `ProblemJson`, `ErrorResponse`, `Metadata`.
-- Деривы `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]`,
-  `#[masterror(...)]`, `#[provide]` для типизированного телеметрического
-  контекста и прямых конверсий доменных ошибок.
-- Адаптеры для Axum и Actix плюс логирование в браузер/`JsValue` для WASM (по
-  фичам).
-- Генерация схем OpenAPI через `utoipa`.
-- Структурированные поля `Metadata` через билдеры `field::*`.
-- Конверсии из распространённых библиотек (`sqlx`, `reqwest`, `redis`,
-  `validator`, `config`, `tokio` и др.).
-- Готовый прелюдия-модуль и расширение `turnkey` с собственной таксономией
-  ошибок.
-
-## Установка
-
-Добавьте зависимость в `Cargo.toml`:
+`masterror` вырос из набора вспомогательных функций в полноценный workspace с
+модульными крейтами для построения наблюдаемых и последовательных ошибок в
+Rust-сервисах. Базовый крейт остаётся независимым от веб-фреймворков, а фичи
+включают только нужные адаптеры, интеграции и телеметрию. `unsafe` запрещён,
+MSRV зафиксирован, а родные деривы позволяют доменным типам управлять
+редактированием сообщений и метаданными.
+
+## Ключевые возможности
+
+- **Единая таксономия.** `AppError`, `AppErrorKind` и `AppCode` описывают
+  доменные и транспортные аспекты, имеют консервативное соответствие HTTP/gRPC,
+  готовые подсказки retry/auth и RFC7807-ответы через `ProblemJson`.
+- **Родные деривы.** `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]`,
+  `#[masterror(...)]` и `#[provide]` соединяют ваши типы с `AppError`, пробрасывая
+  источники, бэктрейсы, телеметрию и политику редактирования.
+- **Типизированная телеметрия.** `Metadata` хранит структурированные ключи и
+  значения с индивидуальными правилами маскирования, а билдеры `field::*`
+  избавляют от ручных `String`-карт.
+- **Транспортные адаптеры.** Опциональные фичи включают респондеры для Actix/Axum,
+  конвертацию в `tonic::Status`, логирование в браузер/WASM и генерацию схем
+  OpenAPI без утяжеления дефолтной сборки.
+- **Интеграции, проверенные в бою.** Активируйте маппинги для `sqlx`, `reqwest`,
+  `redis`, `validator`, `config`, `tokio`, `teloxide`, `multipart`, Telegram
+  WebApp SDK и других библиотек — каждая переводит ошибки в таксономию с
+  прикреплённой телеметрией.
+- **Готовые настройки.** Модуль `turnkey` поставляет готовый каталог ошибок,
+  билдеры и интеграцию с `tracing` для команд, которым нужна стартовая
+  конфигурация «из коробки».
+
+## Состав workspace
+
+| Крейт | Что содержит | Когда подключать |
+| --- | --- | --- |
+| [`masterror`](https://crates.io/crates/masterror) | Основные типы ошибок, билдеры метаданных, транспорты, интеграции и прелюдия. | Боевые сервисы и библиотеки, которым нужна стабильная поверхность ошибок. |
+| [`masterror-derive`](masterror-derive/README.md) | Процедурные макросы `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]`, `#[provide]`. | Уже идёт транзитивно; подключайте напрямую только для экспериментов с макросами. |
+| [`masterror-template`](masterror-template/README.md) | Общий парсер шаблонов для анализа форматтеров в деривах. | Внутренний компонент; используйте, если нужен этот парсер в другом коде. |
+
+## Флаги фич
+
+Все фичи отключены по умолчанию — выбирайте только нужное.
+
+- **Веб и API:** `axum`, `actix`, `multipart`, `openapi`, `serde_json`.
+- **Наблюдаемость:** `tracing`, `metrics`, `backtrace`.
+- **Async и IO:** `tokio`, `reqwest`, `sqlx`, `sqlx-migrate`, `redis`, `validator`,
+  `config`.
+- **Боты и мессенджеры:** `teloxide`, `telegram-webapp-sdk`.
+- **Фронтенд:** `frontend` для логирования в браузере/WASM.
+- **gRPC:** `tonic` для генерации `tonic::Status`.
+- **Готовая таксономия:** `turnkey`.
+
+## TL;DR
 
 ~~~toml
 [dependencies]
-# минимальное ядро
-masterror = { version = "0.15.0", default-features = false }
-# или с нужными интеграциями
-# masterror = { version = "0.15.0", features = [
+masterror = { version = "0.20.5", default-features = false }
+# или с нужными фичами:
+# masterror = { version = "0.20.5", features = [
 #   "axum", "actix", "openapi", "serde_json",
-#   "sqlx", "sqlx-migrate", "reqwest", "redis",
-#   "validator", "config", "tokio", "multipart",
-#   "teloxide", "telegram-webapp-sdk", "frontend", "turnkey"
+#   "tracing", "metrics", "backtrace", "sqlx",
+#   "sqlx-migrate", "reqwest", "redis", "validator",
+#   "config", "tokio", "multipart", "teloxide",
+#   "telegram-webapp-sdk", "tonic", "frontend", "turnkey"
 # ] }
 ~~~
 
-**MSRV:** 1.90
+---
 
-## Быстрый старт
+### Быстрый старт
 
 Создание ошибки вручную:
 
@@ -78,29 +105,121 @@ fn do_work(flag: bool) -> AppResult<()> {
 }
 ~~~
 
-## Дополнительные интеграции
-
-- `sqlx` — классификация `sqlx::Error` по видам ошибок.
-- `sqlx-migrate` — обработка `sqlx::migrate::MigrateError` как базы данных.
-- `reqwest` — перевод сетевых/HTTP-сбоев в доменные категории.
-- `redis` — корректная обработка ошибок кеша.
-- `validator` — преобразование `ValidationErrors` в валидационные ошибки API.
-- `config` — типизированные ошибки конфигурации.
-- `tokio` — маппинг таймаутов (`tokio::time::error::Elapsed`).
-- `metadata` — типизированные поля `Metadata` без аллокаций строк.
-- `multipart` — обработка ошибок извлечения multipart в Axum.
-- `teloxide` — маппинг `teloxide_core::RequestError` в доменные категории.
-- `telegram-webapp-sdk` — обработка ошибок валидации данных Telegram WebApp.
-- `tonic` — преобразование `AppError` в `tonic::Status` с учётом редактирования.
-- `frontend` — логирование в браузере и преобразование в `JsValue` для WASM.
-- `turnkey` — расширение таксономии для Turnkey SDK.
-
-## Атрибуты `#[provide]` и `#[app_error]`
-
-Атрибут `#[provide(...)]` позволяет передавать структурированную телеметрию через
-`std::error::Request`, а `#[app_error(...)]` описывает прямой маппинг доменной
-ошибки в `AppError` и `AppCode`. Дерив сохраняет синтаксис `thiserror`, но
-дополняет его провайдерами телеметрии и готовыми конверсиями в типы `masterror`.
+### Деривы для доменных ошибок и транспорта
+
+`masterror` предоставляет родные деривы, чтобы типы оставались выразительными, а
+crate отвечал за конверсии, телеметрию и редактирование сообщений.
+
+~~~rust
+use std::io;
+
+use masterror::Error;
+
+#[derive(Debug, Error)]
+#[error("I/O failed: {source}")]
+pub struct DomainError {
+    #[from]
+    #[source]
+    source: io::Error,
+}
+
+#[derive(Debug, Error)]
+#[error(transparent)]
+pub struct WrappedDomainError(
+    #[from]
+    #[source]
+    DomainError
+);
+
+fn load() -> Result<(), DomainError> {
+    Err(io::Error::other("disk offline").into())
+}
+
+let err = load().unwrap_err();
+assert_eq!(err.to_string(), "I/O failed: disk offline");
+
+let wrapped = WrappedDomainError::from(err);
+assert_eq!(wrapped.to_string(), "I/O failed: disk offline");
+~~~
+
+- `use masterror::Error;` подключает макрос дерива.
+- `#[from]` автоматически реализует `From<...>` и проверяет форму враппера.
+- `#[error(transparent)]` гарантирует корректную прокладку `Display`/`source`.
+- `#[app_error(kind = ..., code = ..., message)]` сопоставляет ошибку с
+  `AppError`/`AppCode`; `code = ...` добавляет `From<Error> for AppCode`, а
+  `message` публикует форматированную строку вместо обезличенного текста.
+- `masterror::error::template::ErrorTemplate` разбирает строки формата, позволяя
+  строить собственные деривы без зависимости от `thiserror`.
+
+### Телеметрия, редактирование и маппинги транспортов
+
+`#[derive(Masterror)]` преобразует доменную ошибку в [`masterror::Error`],
+прикрепляя метаданные, политику редактирования и маппинги для HTTP/gRPC/RFC7807.
+
+~~~rust
+use masterror::{
+    mapping::HttpMapping, AppCode, AppErrorKind, Error, Masterror, MessageEditPolicy
+};
+
+#[derive(Debug, Masterror)]
+#[error("user {user_id} missing flag {flag}")]
+#[masterror(
+    code = AppCode::NotFound,
+    category = AppErrorKind::NotFound,
+    message,
+    redact(message, fields("user_id" = hash)),
+    telemetry(
+        Some(masterror::field::str("user_id", user_id.clone())),
+        attempt.map(|value| masterror::field::u64("attempt", value))
+    ),
+    map.grpc = 5,
+    map.problem = "https://errors.example.com/not-found"
+)]
+struct MissingFlag {
+    user_id: String,
+    flag: &'static str,
+    attempt: Option<u64>,
+    #[source]
+    source: Option<std::io::Error>
+}
+
+let err = MissingFlag {
+    user_id: "alice".into(),
+    flag: "beta",
+    attempt: Some(2),
+    source: None
+};
+let converted: Error = err.into();
+assert_eq!(converted.code, AppCode::NotFound);
+assert_eq!(converted.kind, AppErrorKind::NotFound);
+assert_eq!(converted.edit_policy, MessageEditPolicy::Redact);
+assert!(converted.metadata().get("user_id").is_some());
+
+assert_eq!(
+    MissingFlag::HTTP_MAPPING,
+    HttpMapping::new(AppCode::NotFound, AppErrorKind::NotFound)
+);
+~~~
+
+- `code` / `category` задают публичный [`AppCode`] и внутренний
+  [`AppErrorKind`].
+- `message` публикует форматированную строку как безопасное сообщение.
+- `redact(message)` включает редактирование, а `fields("name" = hash)` задаёт
+  правила маскирования для метаданных.
+- `telemetry(...)` принимает выражения, дающие `Option<Field>`; заполненные поля
+  попадают в [`Metadata`].
+- `map.grpc` / `map.problem` добавляют gRPC-код и RFC7807 `type` URI. Дерив
+  генерирует таблицы `HTTP_MAPPING`, `GRPC_MAPPING`, `PROBLEM_MAPPING`.
+
+Все атрибуты уровня полей (`#[from]`, `#[source]`, `#[backtrace]`) продолжают
+работать. Источники и бэктрейсы автоматически прикрепляются к
+[`masterror::Error`].
+
+### Провайдеры телеметрии и `AppError`
+
+`#[provide(...)]` раскрывает структурированную телеметрию через
+`std::error::Request`, а `#[app_error(...)]` описывает конверсию в `AppError` и
+`AppCode`.
 
 ~~~rust
 use std::error::request_ref;
@@ -136,8 +255,8 @@ let via_app = request_ref::<TelemetrySnapshot>(&app).expect("telemetry");
 assert_eq!(via_app.name, "db.query");
 ~~~
 
-Опциональные поля автоматически пропускаются, если значения нет. При запросе
-значения `Option<T>` можно вернуть как по ссылке, так и передать владение:
+Опциональная телеметрия не регистрирует провайдер, если значение `None`, а
+владение можно передать через `value = ...`.
 
 ~~~rust
 use masterror::{AppCode, AppErrorKind, Error};
@@ -162,8 +281,7 @@ assert!(request_ref::<TelemetrySnapshot>(&noisy).is_some());
 assert!(request_ref::<TelemetrySnapshot>(&silent).is_none());
 ~~~
 
-Для перечислений каждая ветка может задавать собственную телеметрию и
-конверсию. Дерив сгенерирует единый `From<Enum>` для `AppError`/`AppCode`:
+Перечисления поддерживают собственные маппинги и провайдеры на вариант:
 
 ~~~rust
 #[derive(Debug, Error)]
@@ -191,252 +309,34 @@ let app: AppError = owned.into();
 assert!(matches!(app.kind, AppErrorKind::Service));
 ~~~
 
-В отличие от `thiserror`, вы получаете дополнительную структурированную
-информацию и прямой маппинг в `AppError`/`AppCode` без ручных реализаций
-`From`.
-
-## `#[derive(Masterror)]` и атрибут `#[masterror(...)]`
-
-Когда нужно сразу получить [`masterror::Error`], используйте `#[derive(Masterror)]`.
-Атрибут `#[masterror(...)]` описывает код, категорию, телеметрию, политику
-редактирования и транспортные подсказки:
-
-~~~rust
-use masterror::{
-    mapping::HttpMapping, AppCode, AppErrorKind, Error, Masterror, MessageEditPolicy
-};
-
-#[derive(Debug, Masterror)]
-#[error("пользователь {user_id} без флага {flag}")]
-#[masterror(
-    code = AppCode::NotFound,
-    category = AppErrorKind::NotFound,
-    message,
-    redact(message, fields("user_id" = hash)),
-    telemetry(
-        Some(masterror::field::str("user_id", user_id.clone())),
-        attempt.map(|value| masterror::field::u64("attempt", value))
-    ),
-    map.grpc = 5,
-    map.problem = "https://errors.example.com/not-found"
-)]
-struct MissingFlag {
-    user_id: String,
-    flag: &'static str,
-    attempt: Option<u64>,
-    #[source]
-    source: Option<std::io::Error>,
-}
-
-let err = MissingFlag {
-    user_id: "alice".into(),
-    flag: "beta",
-    attempt: Some(2),
-    source: None,
-};
-let converted: Error = err.into();
-assert_eq!(converted.code, AppCode::NotFound);
-assert_eq!(converted.kind, AppErrorKind::NotFound);
-assert_eq!(converted.edit_policy, MessageEditPolicy::Redact);
-assert!(converted.metadata().get("user_id").is_some());
-
-assert_eq!(
-    MissingFlag::HTTP_MAPPING,
-    HttpMapping::new(AppCode::NotFound, AppErrorKind::NotFound)
-);
-~~~
-
-- `code` / `category` задают публичный [`AppCode`] и внутренний
-  [`AppErrorKind`].
-- `message` включает текст, возвращаемый [`Display`], в публичное сообщение.
-- `redact(message)` выставляет [`MessageEditPolicy`] в режим редактирования на
-  транспортной границе, `fields("name" = hash, "card" = last4)` переопределяет
-  обработку метаданных (`hash`, `last4`, `redact`, `none`).
-- `telemetry(...)` принимает выражения, возвращающие
-  `Option<masterror::Field>`. Каждое присутствующее поле добавляется в
-  [`Metadata`]; пустые выражения пропускаются.
-- `map.grpc` / `map.problem` позволяют зафиксировать код gRPC (целое `i32`) и
-  URI для problem+json. Дерив генерирует таблицы `TYPE::HTTP_MAPPING`,
-  `TYPE::GRPC_MAPPING` и `TYPE::PROBLEM_MAPPING` (или срезы для перечислений)
-  для дальнейшей интеграции.
-
-Атрибуты `#[from]`, `#[source]`, `#[backtrace]` продолжают работать: источники и
-бектрейсы автоматически прикрепляются к результирующему [`masterror::Error`].
-
-## Форматирование шаблонов `#[error]`
-
-Шаблон `#[error("...")]` по умолчанию использует `Display`, но любая
-подстановка может запросить другой форматтер.
-`TemplateFormatter::is_alternate()` фиксирует флаг `#`, а `TemplateFormatterKind`
-сообщает, какой трейт `core::fmt` нужен, поэтому порождённый код может
-переключаться между вариантами без ручного `match`. Неподдержанные спецификаторы
-приводят к диагностике на этапе компиляции, совпадающей с `thiserror`.
-
-| Спецификатор     | Трейт                   | Пример результата        | Примечания |
-|------------------|-------------------------|--------------------------|------------|
-| _по умолчанию_   | `core::fmt::Display`    | `value`                  | Пользовательские сообщения; `#` игнорируется. |
-| `:?` / `:#?`     | `core::fmt::Debug`      | `Struct { .. }` / многострочный | Поведение `Debug`; `#` включает pretty-print. |
-| `:x` / `:#x`     | `core::fmt::LowerHex`   | `0x2a`                   | Шестнадцатеричный вывод; `#` добавляет `0x`. |
-| `:X` / `:#X`     | `core::fmt::UpperHex`   | `0x2A`                   | Верхний регистр; `#` добавляет `0x`. |
-| `:p` / `:#p`     | `core::fmt::Pointer`    | `0x1f00` / `0x1f00`      | Сырые указатели; `#` поддерживается для совместимости. |
-| `:b` / `:#b`     | `core::fmt::Binary`     | `101010` / `0b101010`   | Двоичный вывод; `#` добавляет `0b`. |
-| `:o` / `:#o`     | `core::fmt::Octal`      | `52` / `0o52`           | Восьмеричный вывод; `#` добавляет `0o`. |
-| `:e` / `:#e`     | `core::fmt::LowerExp`   | `1.5e-2`                | Научная запись; `#` заставляет выводить десятичную точку. |
-| `:E` / `:#E`     | `core::fmt::UpperExp`   | `1.5E-2`                | Верхний регистр научной записи; `#` заставляет выводить точку. |
-
-- `TemplateFormatterKind::supports_alternate()` сообщает, имеет ли смысл `#` для
-  выбранного трейта (для указателей вывод совпадает с обычным).
-- `TemplateFormatterKind::specifier()` возвращает канонический символ
-  спецификатора, что упрощает повторный рендеринг плейсхолдеров.
-- `TemplateFormatter::from_kind(kind, alternate)` собирает форматтер из
-  `TemplateFormatterKind`, позволяя программно переключать флаг `#`.
-- Display-плейсхолдеры сохраняют исходные параметры форматирования:
-  методы `TemplateFormatter::display_spec()` и
-  `TemplateFormatter::format_fragment()` возвращают `:>8`, `:.3` и другие
-  варианты без необходимости собирать строку вручную.
-
-~~~rust
-use core::ptr;
-
-use masterror::Error;
-
-#[derive(Debug, Error)]
-#[error(
-    "debug={payload:?}, hex={id:#x}, ptr={ptr:p}, bin={mask:#b}, \
-     oct={mask:o}, lower={ratio:e}, upper={ratio:E}"
-)]
-struct FormatterDemo {
-    id: u32,
-    payload: String,
-    ptr: *const u8,
-    mask: u8,
-    ratio: f32,
-}
-
-let err = FormatterDemo {
-    id: 0x2a,
-    payload: "hello".into(),
-    ptr: ptr::null(),
-    mask: 0b1010_0001,
-    ratio: 0.15625,
-};
-
-let rendered = err.to_string();
-assert!(rendered.contains("debug=\"hello\""));
-assert!(rendered.contains("hex=0x2a"));
-assert!(rendered.contains("ptr=0x0"));
-assert!(rendered.contains("bin=0b10100001"));
-assert!(rendered.contains("oct=241"));
-assert!(rendered.contains("lower=1.5625e-1"));
-assert!(rendered.contains("upper=1.5625E-1"));
-~~~
+Так вы сохраняете знакомый интерфейс `thiserror`, но получаете телеметрию и
+готовые конверсии в `AppError`/`AppCode` без ручного кода.
 
-`masterror::error::template::ErrorTemplate` позволяет разобрать шаблон и
-программно проверить запрошенные форматтеры; перечисление
-`TemplateFormatterKind` возвращает название трейта для каждого плейсхолдера:
+### Problem JSON и подсказки retry/auth
 
 ~~~rust
-use masterror::error::template::{
-    ErrorTemplate, TemplateFormatter, TemplateFormatterKind
-};
+use masterror::{AppError, AppErrorKind, ProblemJson};
+use std::time::Duration;
 
-let template = ErrorTemplate::parse("{code:#x} → {payload:?}").expect("parse");
-let mut placeholders = template.placeholders();
-
-let code = placeholders.next().expect("code placeholder");
-let code_formatter = code.formatter();
-assert!(matches!(
-    code_formatter,
-    TemplateFormatter::LowerHex { alternate: true }
-));
-let code_kind = code_formatter.kind();
-assert_eq!(code_kind, TemplateFormatterKind::LowerHex);
-assert!(code_formatter.is_alternate());
-assert_eq!(code_kind.specifier(), Some('x'));
-assert!(code_kind.supports_alternate());
-let lowered = TemplateFormatter::from_kind(code_kind, false);
-assert!(matches!(
-    lowered,
-    TemplateFormatter::LowerHex { alternate: false }
-));
-
-let payload = placeholders.next().expect("payload placeholder");
-let payload_formatter = payload.formatter();
-assert_eq!(
-    payload_formatter,
-    &TemplateFormatter::Debug { alternate: false }
+let problem = ProblemJson::from_app_error(
+    AppError::new(AppErrorKind::Unauthorized, "Token expired")
+        .with_retry_after_duration(Duration::from_secs(30))
+        .with_www_authenticate(r#"Bearer realm="api", error="invalid_token""#)
 );
-let payload_kind = payload_formatter.kind();
-assert_eq!(payload_kind, TemplateFormatterKind::Debug);
-assert_eq!(payload_kind.specifier(), Some('?'));
-assert!(payload_kind.supports_alternate());
-let pretty_debug = TemplateFormatter::from_kind(payload_kind, true);
-assert!(matches!(
-    pretty_debug,
-    TemplateFormatter::Debug { alternate: true }
-));
-assert!(pretty_debug.is_alternate());
-~~~
 
-Опции выравнивания, точности и заполнения для `Display` сохраняются и доступны
-для прямой передачи в `write!`:
-
-~~~rust
-use masterror::error::template::ErrorTemplate;
-
-let aligned = ErrorTemplate::parse("{value:>8}").expect("parse");
-let display = aligned.placeholders().next().expect("display placeholder");
-assert_eq!(display.formatter().display_spec(), Some(">8"));
-assert_eq!(
-    display
-        .formatter()
-        .format_fragment()
-        .as_deref(),
-    Some(">8")
-);
+assert_eq!(problem.status, 401);
+assert_eq!(problem.retry_after, Some(30));
+assert_eq!(problem.grpc.expect("grpc").name, "UNAUTHENTICATED");
 ~~~
 
-Динамические ширина и точность (`{value:>width$}`, `{value:.precision$}`)
-тоже доходят до вызова `write!`, если объявить соответствующие аргументы в
-атрибуте `#[error(...)]`:
-
-~~~rust
-use masterror::Error;
-
-#[derive(Debug, Error)]
-#[error("{value:>width$}", value = .value, width = .width)]
-struct DynamicWidth {
-    value: &'static str,
-    width: usize,
-}
-
-#[derive(Debug, Error)]
-#[error("{value:.precision$}", value = .value, precision = .precision)]
-struct DynamicPrecision {
-    value: f64,
-    precision: usize,
-}
-
-let width = DynamicWidth {
-    value: "x",
-    width: 5,
-};
-let precision = DynamicPrecision {
-    value: 123.456_f64,
-    precision: 4,
-};
-
-assert_eq!(width.to_string(), format!("{value:>width$}", value = "x", width = 5));
-assert_eq!(
-    precision.to_string(),
-    format!("{value:.precision$}", value = 123.456_f64, precision = 4)
-);
-~~~
+### Дополнительные материалы
 
-> **Совместимость с `thiserror` v2.** Доступные спецификаторы, сообщения об
-> ошибках и поведение совпадают с `thiserror` 2.x, поэтому миграция с
-> `thiserror::Error` на `masterror::Error` не требует переписывать шаблоны.
+- [Вики по обработке ошибок](docs/wiki/index.md) с пошаговыми руководствами,
+  сравнением `thiserror`/`anyhow` и рецептами устранения проблем.
+- [Документация на docs.rs](https://docs.rs/masterror) с подробными таблицами по
+  фичам и транспортам.
+- [`CHANGELOG.md`](CHANGELOG.md) для истории релизов и миграций.
 
-## Лицензия
+---
 
-Проект распространяется по лицензии Apache-2.0 или MIT на ваш выбор.
+MSRV: **1.90** · Лицензия: **MIT OR Apache-2.0** · Без `unsafe`
diff --git a/README.template.md b/README.template.md
index 1095ee8..1f743b3 100644
--- a/README.template.md
+++ b/README.template.md
@@ -14,25 +14,58 @@
 
 > 🇷🇺 Читайте README на [русском языке](README.ru.md).
 
-Small, pragmatic error model for API-heavy Rust services with native derives
-and typed telemetry.
-Core is framework-agnostic; integrations are opt-in via feature flags.
-Stable categories, conservative HTTP mapping, no `unsafe`.
-
-- Core types: `AppError`, `AppErrorKind`, `AppResult`, `AppCode`, `ProblemJson`, `ErrorResponse`, `Metadata`
-- Derive macros: `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]`,
-  `#[masterror(...)]`, `#[provide]` for domain mappings and structured
-  telemetry
-- Optional Axum/Actix integration and browser/WASM console logging
-- Optional OpenAPI schema (via `utoipa`)
-- Structured metadata helpers via `field::*` builders
-- Conversions from `sqlx`, `reqwest`, `redis`, `validator`, `config`, `tokio`
-- Turnkey domain taxonomy and helpers (`turnkey` feature)
-
-👉 Explore the new [error-handling wiki](docs/wiki/index.md) for step-by-step
-guides, comparisons with `thiserror`/`anyhow`, and troubleshooting recipes.
-
----
+`masterror` grew from a handful of helpers into a workspace of composable crates for
+building consistent, observable error surfaces across Rust services. The core
+crate stays framework-agnostic, while feature flags light up transport adapters,
+integrations and telemetry without pulling in heavyweight defaults. No
+`unsafe`, MSRV is pinned, and the derive macros keep your domain types in charge
+of redaction and metadata.
+
+### Highlights
+
+- **Unified taxonomy.** `AppError`, `AppErrorKind` and `AppCode` model domain and
+  transport concerns with conservative HTTP/gRPC mappings, turnkey retry/auth
+  hints and RFC7807 output via `ProblemJson`.
+- **Native derives.** `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]`,
+  `#[masterror(...)]` and `#[provide]` wire custom types into `AppError` while
+  forwarding sources, backtraces, telemetry providers and redaction policy.
+- **Typed telemetry.** `Metadata` stores structured key/value context with
+  per-field redaction controls and builders in `field::*`, so logs stay
+  structured without manual `String` maps.
+- **Transport adapters.** Optional features expose Actix/Axum responders,
+  `tonic::Status` conversions, WASM/browser logging and OpenAPI schema
+  generation without contaminating the lean default build.
+- **Battle-tested integrations.** Enable focused mappings for `sqlx`,
+  `reqwest`, `redis`, `validator`, `config`, `tokio`, `teloxide`, `multipart`,
+  Telegram WebApp SDK and more — each translating library errors into the
+  taxonomy with telemetry attached.
+- **Turnkey defaults.** The `turnkey` module ships a ready-to-use error catalog,
+  helper builders and tracing instrumentation for teams that want a consistent
+  baseline out of the box.
+
+### Workspace crates
+
+| Crate | What it provides | When to depend on it |
+| --- | --- | --- |
+| [`masterror`](https://crates.io/crates/masterror) | Core error types, metadata builders, transports, integrations and the prelude. | Application crates, services and libraries that want a stable error surface. |
+| [`masterror-derive`](masterror-derive/README.md) | Proc-macros backing `#[derive(Error)]`, `#[derive(Masterror)]`, `#[app_error]` and `#[provide]`. | Brought in automatically via `masterror`; depend directly only for macro hacking. |
+| [`masterror-template`](masterror-template/README.md) | Shared template parser used by the derive macros for formatter analysis. | Internal dependency; reuse when you need the template parser elsewhere. |
+
+### Feature flags at a glance
+
+Pick only what you need; everything is off by default.
+
+- **Web transports:** `axum`, `actix`, `multipart`, `openapi`, `serde_json`.
+- **Telemetry & observability:** `tracing`, `metrics`, `backtrace`.
+- **Async & IO integrations:** `tokio`, `reqwest`, `sqlx`, `sqlx-migrate`,
+  `redis`, `validator`, `config`.
+- **Messaging & bots:** `teloxide`, `telegram-webapp-sdk`.
+- **Front-end tooling:** `frontend` for WASM/browser console logging.
+- **gRPC:** `tonic` to emit `tonic::Status` responses.
+- **Batteries included:** `turnkey` to adopt the pre-built taxonomy and helpers.
+
+The build script keeps the full feature snippet below in sync with
+`Cargo.toml`.
 
 ### TL;DR
 
@@ -45,48 +78,8 @@ masterror = { version = "{{CRATE_VERSION}}", default-features = false }
 # ] }
 ~~~
 
-*Since v0.5.0: derive custom errors via `#[derive(Error)]` (`use masterror::Error;`) and inspect browser logging failures with `BrowserConsoleError::context()`.*
-*Since v0.4.0: optional `frontend` feature for WASM/browser console logging.*
-*Since v0.3.0: stable `AppCode` enum and extended `ErrorResponse` with retry/authentication metadata.*
-*Since v0.15.0: RFC7807 `ProblemJson` responses for HTTP integrations and `tonic::Status` conversion.*
-
 ---
 
-<details>
-  <summary><b>Why this crate?</b></summary>
-
-- **Stable taxonomy.** Small set of `AppErrorKind` categories mapping conservatively to HTTP.
-- **Framework-agnostic.** No assumptions, no `unsafe`, MSRV pinned.
-- **Opt-in integrations.** Zero default features; you enable what you need.
-- **Clean wire contract.** `ProblemJson { type?, title, status, detail?, code, grpc?, metadata? }` with `Retry-After` / `WWW-Authenticate` headers when present.
-- **Typed telemetry.** `Metadata` preserves structured key/value context without `String` maps.
-- **One log at boundary.** Log once with `tracing`.
-- **Less boilerplate.** Built-in conversions, compact prelude, and the
-  native `masterror::Error` derive with `#[from]` / `#[error(transparent)]`
-  support.
-- **Consistent workspace.** Same error surface across crates.
-
-</details>
-
-<details>
-  <summary><b>Installation</b></summary>
-
-~~~toml
-[dependencies]
-# lean core
-masterror = { version = "{{CRATE_VERSION}}", default-features = false }
-
-# with Axum/Actix + JSON + integrations
-# masterror = { version = "{{CRATE_VERSION}}", features = [
-{{FEATURE_SNIPPET}}
-# ] }
-~~~
-
-**MSRV:** {{MSRV}}
-**No unsafe:** forbidden by crate.
-
-</details>
-
 <details>
   <summary><b>Quick start</b></summary>
 
@@ -118,7 +111,10 @@ fn do_work(flag: bool) -> AppResult<()> {
 </details>
 
 <details>
-  <summary><b>Derive custom errors</b></summary>
+  <summary><b>Derive domain errors and map them to transports</b></summary>
+
+`masterror` ships native derives so your domain types stay expressive while the
+crate handles conversions, telemetry and redaction for you.
 
 ~~~rust
 use std::io;
@@ -152,7 +148,7 @@ let wrapped = WrappedDomainError::from(err);
 assert_eq!(wrapped.to_string(), "I/O failed: disk offline");
 ~~~
 
-- `use masterror::Error;` brings the crate's derive macro into scope.
+- `use masterror::Error;` brings the derive macro into scope.
 - `#[from]` automatically implements `From<...>` while ensuring wrapper shapes are
   valid.
 - `#[error(transparent)]` enforces single-field wrappers that forward
@@ -175,12 +171,15 @@ assert_eq!(wrapped.to_string(), "I/O failed: disk offline");
   placeholder, making it easy to branch on the requested rendering behaviour
   without manually matching every enum variant.
 
-#### `#[derive(Masterror)]` and `#[masterror(...)]`
+</details>
+
+<details>
+  <summary><b>Attach telemetry, redaction policy and conversions</b></summary>
 
-`#[derive(Masterror)]` wires a domain error directly into [`masterror::Error`],
-augmenting it with metadata, redaction policy and optional transport mappings.
-The accompanying `#[masterror(...)]` attribute mirrors the `#[app_error]`
-syntax while remaining explicit about telemetry:
+`#[derive(Masterror)]` wires a domain error into [`masterror::Error`], adds
+metadata, redaction policy and optional transport mappings. The accompanying
+`#[masterror(...)]` attribute mirrors the `#[app_error]` syntax while staying
+explicit about telemetry and redaction.
 
 ~~~rust
 use masterror::{
@@ -247,103 +246,10 @@ All familiar field-level attributes (`#[from]`, `#[source]`, `#[backtrace]`)
 are still honoured. Sources and backtraces are automatically attached to the
 generated [`masterror::Error`].
 
-#### Display shorthand projections
-
-`#[error("...")]` supports the same shorthand syntax as `thiserror` for
-referencing fields with `.field` or `.0`. The derive now understands chained
-segments, so projections like `.limits.lo`, `.0.data` or
-`.suggestion.as_ref().map_or_else(...)` keep compiling unchanged. Raw
-identifiers and tuple indices are preserved, ensuring keywords such as
-`r#type` and tuple fields continue to work even when you call methods on the
-projected value.
-
-~~~rust
-use masterror::Error;
-
-#[derive(Debug)]
-struct Limits {
-    lo: i32,
-    hi: i32,
-}
-
-#[derive(Debug, Error)]
-#[error(
-    "range {lo}-{hi} suggestion {suggestion}",
-    lo = .limits.lo,
-    hi = .limits.hi,
-    suggestion = .suggestion.as_ref().map_or_else(|| "<none>", |s| s.as_str())
-)]
-struct RangeError {
-    limits: Limits,
-    suggestion: Option<String>,
-}
-
-#[derive(Debug)]
-struct Payload {
-    data: &'static str,
-}
-
-#[derive(Debug, Error)]
-enum UiError {
-    #[error("tuple data {data}", data = .0.data)]
-    Tuple(Payload),
-    #[error(
-        "named suggestion {value}",
-        value = .suggestion.as_ref().map_or_else(|| "<none>", |s| s.as_str())
-    )]
-    Named { suggestion: Option<String> },
-}
-~~~
-
-#### AppError conversions
-
-Annotating structs or enum variants with `#[app_error(...)]` captures the
-metadata required to convert the domain error into `AppError` (and optionally
-`AppCode`). Every variant in an enum must provide the mapping when any variant
-requests it.
-
-~~~rust
-use masterror::{AppCode, AppError, AppErrorKind, Error};
-
-#[derive(Debug, Error)]
-#[error("missing flag: {name}")]
-#[app_error(kind = AppErrorKind::BadRequest, code = AppCode::BadRequest, message)]
-struct MissingFlag {
-    name: &'static str,
-}
-
-let app: AppError = MissingFlag { name: "feature" }.into();
-assert!(matches!(app.kind, AppErrorKind::BadRequest));
-assert_eq!(app.message.as_deref(), Some("missing flag: feature"));
-
-let code: AppCode = MissingFlag { name: "feature" }.into();
-assert!(matches!(code, AppCode::BadRequest));
-~~~
-
-For enums, each variant specifies the mapping while the derive generates a
-single `From<Enum>` implementation that matches every variant:
-
-~~~rust
-#[derive(Debug, Error)]
-enum ApiError {
-    #[error("missing resource {id}")]
-    #[app_error(
-        kind = AppErrorKind::NotFound,
-        code = AppCode::NotFound,
-        message
-    )]
-    Missing { id: u64 },
-    #[error("backend unavailable")]
-    #[app_error(kind = AppErrorKind::Service, code = AppCode::Service)]
-    Backend,
-}
-
-let missing = ApiError::Missing { id: 7 };
-let as_app: AppError = missing.into();
-assert_eq!(as_app.message.as_deref(), Some("missing resource 7"));
-~~~
+</details>
 
-#### Structured telemetry providers and AppError mappings
+<details>
+  <summary><b>Structured telemetry providers and AppError mappings</b></summary>
 
 `#[provide(...)]` exposes typed context through `std::error::Request`, while
 `#[app_error(...)]` records how your domain error translates into `AppError`
@@ -444,173 +350,12 @@ assert!(matches!(app.kind, AppErrorKind::Service));
 
 Compared to `thiserror`, you retain the familiar deriving surface while gaining
 structured telemetry (`#[provide]`) and first-class conversions into
-`AppError`/`AppCode` without writing manual `From` implementations.
-
-#### Formatter traits
-
-Placeholders default to `Display` (`{value}`) but can opt into richer
-formatters via the same specifiers supported by `thiserror` v2.
-`TemplateFormatter::is_alternate()` tracks the `#` flag, while
-`TemplateFormatterKind` exposes the underlying `core::fmt` trait so derived
-code can branch on the requested renderer without manual pattern matching.
-Unsupported formatters surface a compile error that mirrors `thiserror`'s
-diagnostics.
-
-| Specifier        | `core::fmt` trait          | Example output         | Notes |
-|------------------|----------------------------|------------------------|-------|
-| _default_        | `core::fmt::Display`       | `value`                | User-facing strings; `#` has no effect. |
-| `:?` / `:#?`     | `core::fmt::Debug`         | `Struct { .. }` / multi-line | Mirrors `Debug`; `#` pretty-prints structs. |
-| `:x` / `:#x`     | `core::fmt::LowerHex`      | `0x2a`                 | Hexadecimal; `#` prepends `0x`. |
-| `:X` / `:#X`     | `core::fmt::UpperHex`      | `0x2A`                 | Uppercase hex; `#` prepends `0x`. |
-| `:p` / `:#p`     | `core::fmt::Pointer`       | `0x1f00` / `0x1f00`    | Raw pointers; `#` is accepted for compatibility. |
-| `:b` / `:#b`     | `core::fmt::Binary`        | `101010` / `0b101010` | Binary; `#` prepends `0b`. |
-| `:o` / `:#o`     | `core::fmt::Octal`         | `52` / `0o52`         | Octal; `#` prepends `0o`. |
-| `:e` / `:#e`     | `core::fmt::LowerExp`      | `1.5e-2`              | Scientific notation; `#` forces the decimal point. |
-| `:E` / `:#E`     | `core::fmt::UpperExp`      | `1.5E-2`              | Uppercase scientific; `#` forces the decimal point. |
-
-- `TemplateFormatterKind::supports_alternate()` reports whether the `#` flag is
-  meaningful for the requested trait (pointer accepts it even though the output
-  matches the non-alternate form).
-- `TemplateFormatterKind::specifier()` returns the canonical format specifier
-  character when one exists, enabling custom derives to re-render placeholders
-  in their original style.
-- `TemplateFormatter::from_kind(kind, alternate)` reconstructs a formatter from
-  the lightweight `TemplateFormatterKind`, making it easy to toggle the
-  alternate flag in generated code.
-
-~~~rust
-use core::ptr;
-
-use masterror::Error;
-
-#[derive(Debug, Error)]
-#[error(
-    "debug={payload:?}, hex={id:#x}, ptr={ptr:p}, bin={mask:#b}, \
-     oct={mask:o}, lower={ratio:e}, upper={ratio:E}"
-)]
-struct FormattedError {
-    id: u32,
-    payload: String,
-    ptr: *const u8,
-    mask: u8,
-    ratio: f32,
-}
-
-let err = FormattedError {
-    id: 0x2a,
-    payload: "hello".into(),
-    ptr: ptr::null(),
-    mask: 0b1010_0001,
-    ratio: 0.15625,
-};
-
-let rendered = err.to_string();
-assert!(rendered.contains("debug=\"hello\""));
-assert!(rendered.contains("hex=0x2a"));
-assert!(rendered.contains("ptr=0x0"));
-assert!(rendered.contains("bin=0b10100001"));
-assert!(rendered.contains("oct=241"));
-assert!(rendered.contains("lower=1.5625e-1"));
-assert!(rendered.contains("upper=1.5625E-1"));
-~~~
-
-~~~rust
-use masterror::error::template::{
-    ErrorTemplate, TemplateFormatter, TemplateFormatterKind
-};
-
-let template = ErrorTemplate::parse("{code:#x} → {payload:?}").expect("parse");
-let mut placeholders = template.placeholders();
-
-let code = placeholders.next().expect("code placeholder");
-let code_formatter = code.formatter();
-assert!(matches!(
-    code_formatter,
-    TemplateFormatter::LowerHex { alternate: true }
-));
-let code_kind = code_formatter.kind();
-assert_eq!(code_kind, TemplateFormatterKind::LowerHex);
-assert!(code_formatter.is_alternate());
-assert_eq!(code_kind.specifier(), Some('x'));
-assert!(code_kind.supports_alternate());
-let lowered = TemplateFormatter::from_kind(code_kind, false);
-assert!(matches!(
-    lowered,
-    TemplateFormatter::LowerHex { alternate: false }
-));
-
-let payload = placeholders.next().expect("payload placeholder");
-let payload_formatter = payload.formatter();
-assert_eq!(
-    payload_formatter,
-    &TemplateFormatter::Debug { alternate: false }
-);
-let payload_kind = payload_formatter.kind();
-assert_eq!(payload_kind, TemplateFormatterKind::Debug);
-assert_eq!(payload_kind.specifier(), Some('?'));
-assert!(payload_kind.supports_alternate());
-let pretty_debug = TemplateFormatter::from_kind(payload_kind, true);
-assert!(matches!(
-    pretty_debug,
-    TemplateFormatter::Debug { alternate: true }
-));
-assert!(pretty_debug.is_alternate());
-~~~
-
-Display-only format specs (alignment, precision, fill — including `#` as a fill
-character) are preserved so you can forward them to `write!` without rebuilding
-the fragment:
-
-~~~rust
-use masterror::error::template::ErrorTemplate;
-
-let aligned = ErrorTemplate::parse("{value:>8}").expect("parse");
-let display = aligned.placeholders().next().expect("display placeholder");
-assert_eq!(display.formatter().display_spec(), Some(">8"));
-assert_eq!(
-    display
-        .formatter()
-        .format_fragment()
-        .as_deref(),
-    Some(">8")
-);
-
-let hashed = ErrorTemplate::parse("{value:#>4}").expect("parse");
-let hash_placeholder = hashed
-    .placeholders()
-    .next()
-    .expect("hash-fill display placeholder");
-assert_eq!(hash_placeholder.formatter().display_spec(), Some("#>4"));
-assert_eq!(
-    hash_placeholder
-        .formatter()
-        .format_fragment()
-        .as_deref(),
-    Some("#>4")
-);
-~~~
-
-> **Compatibility with `thiserror` v2:** the derive understands the extended
-> formatter set introduced in `thiserror` 2.x and reports identical diagnostics
-> for unsupported specifiers, so migrating existing derives is drop-in.
-
-```rust
-use masterror::error::template::{ErrorTemplate, TemplateIdentifier};
-
-let template = ErrorTemplate::parse("{code}: {message}").expect("parse");
-let display = template.display_with(|placeholder, f| match placeholder.identifier() {
-    TemplateIdentifier::Named("code") => write!(f, "{}", 404),
-    TemplateIdentifier::Named("message") => f.write_str("Not Found"),
-    _ => Ok(()),
-});
-
-assert_eq!(display.to_string(), "404: Not Found");
-```
+`AppError`/`AppCode` without manual glue.
 
 </details>
 
 <details>
-  <summary><b>Error response payload</b></summary>
+  <summary><b>Problem JSON payloads and retry/authentication hints</b></summary>
 
 ~~~rust
 use masterror::{AppError, AppErrorKind, ProblemJson};
@@ -629,143 +374,14 @@ assert_eq!(problem.grpc.expect("grpc").name, "UNAUTHENTICATED");
 
 </details>
 
-<details>
-  <summary><b>Web framework integrations</b></summary>
-
-<details>
-  <summary>Axum</summary>
-
-~~~rust
-// features = ["axum", "serde_json"]
-...
-    assert!(payload.is_object());
-
-    #[cfg(target_arch = "wasm32")]
-    {
-        if let Err(console_err) = err.log_to_browser_console() {
-            eprintln!(
-                "failed to log to browser console: {:?}",
-                console_err.context()
-            );
-        }
-    }
-
-    Ok(())
-}
-~~~
-
-- On non-WASM targets `log_to_browser_console` returns
-  `BrowserConsoleError::UnsupportedTarget`.
-- `BrowserConsoleError::context()` exposes optional browser diagnostics for
-  logging/telemetry when console logging fails.
-
-</details>
-
-</details>
-
-<details>
-  <summary><b>Feature flags</b></summary>
-
-{{FEATURE_BULLETS}}
-
-</details>
-
-<details>
-  <summary><b>Conversions</b></summary>
-
-{{CONVERSION_BULLETS}}
-
-</details>
-
-<details>
-  <summary><b>Typical setups</b></summary>
-
-Minimal core:
-
-~~~toml
-masterror = { version = "{{CRATE_VERSION}}", default-features = false }
-~~~
-
-API (Axum + JSON + deps):
-
-~~~toml
-masterror = { version = "{{CRATE_VERSION}}", features = [
-  "axum", "serde_json", "openapi",
-  "sqlx", "reqwest", "redis", "validator", "config", "tokio"
-] }
-~~~
-
-API (Actix + JSON + deps):
-
-~~~toml
-masterror = { version = "{{CRATE_VERSION}}", features = [
-  "actix", "serde_json", "openapi",
-  "sqlx", "reqwest", "redis", "validator", "config", "tokio"
-] }
-~~~
-
-</details>
-
-<details>
-  <summary><b>Turnkey</b></summary>
-
-~~~rust
-// features = ["turnkey"]
-use masterror::turnkey::{classify_turnkey_error, TurnkeyError, TurnkeyErrorKind};
-use masterror::{AppError, AppErrorKind};
-
-// Classify a raw SDK/provider error
-let kind = classify_turnkey_error("429 Too Many Requests");
-assert!(matches!(kind, TurnkeyErrorKind::RateLimited));
-
-// Wrap into AppError
-let e = TurnkeyError::new(TurnkeyErrorKind::RateLimited, "throttled upstream");
-let app: AppError = e.into();
-assert_eq!(app.kind, AppErrorKind::RateLimited);
-~~~
-
-</details>
-
-<details>
-  <summary><b>Migration 0.2 → 0.3</b></summary>
-
-- Use `ErrorResponse::new(status, AppCode::..., "msg")` instead of legacy
-- New helpers: `.with_retry_after_secs`, `.with_retry_after_duration`, `.with_www_authenticate`
-- `ErrorResponse::new_legacy` is temporary shim
-
-</details>
-
-<details>
-  <summary><b>Versioning & MSRV</b></summary>
+### Further resources
 
-Semantic versioning. Breaking API/wire contract → major bump.
-MSRV = {{MSRV}} (may raise in minor, never in patch).
+- Explore the [error-handling wiki](docs/wiki/index.md) for step-by-step guides,
+  comparisons with `thiserror`/`anyhow`, and troubleshooting recipes.
+- Browse the [crate documentation on docs.rs](https://docs.rs/masterror) for API
+  details, feature-specific guides and transport tables.
+- Check [`CHANGELOG.md`](CHANGELOG.md) for release highlights and migration notes.
 
-</details>
-
-<details>
-  <summary><b>Release checklist</b></summary>
-
-1. `cargo +nightly fmt --`
-1. `cargo clippy -- -D warnings`
-1. `cargo test --all`
-1. `cargo build` (regenerates README.md from the template)
-1. `cargo doc --no-deps`
-1. `cargo package --locked`
-
-</details>
-
-<details>
-  <summary><b>Non-goals</b></summary>
-
-- Not a general-purpose error aggregator like `anyhow`
-- Not a replacement for your domain errors
-
-</details>
-
-<details>
-  <summary><b>License</b></summary>
-
-Apache-2.0 OR MIT, at your option.
+---
 
-</details>
+MSRV: **{{MSRV}}** · License: **MIT OR Apache-2.0** · No `unsafe`