docs: document attrs_mapping for selective attribute deprecation

- Add "Selective attribute deprecation" section to docs/guide/use-cases.md with example, output block, and audit-visibility note
- Add attrs_mapping <details> example block to README.md Enums/dataclasses section; add attrs_mapping to deprecated_class param tip
- Add recipe, Decision Table row, flowchart branch, numbered decision step, and Agent Notes entry to docs/llms.txt

---
Co-authored-by: Claude Code <noreply@anthropic.com>

Author: Borda

README.md

@@ -253,7 +253,7 @@ Not sure which API to reach for? Start here.
 | `update_docstring` | `False`                     | Append Sphinx `.. deprecated::` notice to docstring                                                        |
 
 > [!TIP]
-> `@deprecated_class()` shares `target`, `deprecated_in`, `remove_in`, `num_warns`, `stream`, `args_mapping`, `args_extra`, `template_mgs`, `update_docstring`, and `docstring_style`.
+> `@deprecated_class()` shares `target`, `deprecated_in`, `remove_in`, `num_warns`, `stream`, `args_mapping`, `attrs_mapping`, `args_extra`, `template_mgs`, `update_docstring`, and `docstring_style`.
 > `deprecated_instance()` shares `deprecated_in`, `remove_in`, `num_warns`, `stream`, `args_extra`, and `template_mgs`; it requires `obj` and adds `name` (display name) and `read_only`.
 
 </details>
@@ -917,6 +917,36 @@ True
 
 <br>
 
+<details>
+<summary>Example: selective attribute deprecation with <code>attrs_mapping</code></summary>
+
+Use `attrs_mapping` to deprecate only specific attribute names — other attributes pass through silently. Covers renames, misspelling corrections, and warn-only notices on individual attributes.
+
+```python
+from deprecate import deprecated_class
+
+
+class Config:
+    colour: str = "red"
+    timeout: int = 30
+
+
+# "color" is a deprecated alias for "colour"; access warns and redirects
+DeprecatedConfig = deprecated_class(
+    attrs_mapping={"color": "colour"},
+    deprecated_in="1.0",
+    remove_in="2.0",
+)(Config)
+
+print(DeprecatedConfig.color)  # warns → returns Config.colour ("red")
+print(DeprecatedConfig.colour)  # silent passthrough ("red")
+print(DeprecatedConfig.timeout)  # silent passthrough (30)
+```
+
+</details>
+
+<br>
+
 ### 📝 Automatic docstring updates
 
 You can automatically inject deprecation information into your function's docstring:

docs/guide/use-cases.md

@@ -695,6 +695,56 @@ True
 
 </details>
 
+## Selective attribute deprecation
+
+Use `attrs_mapping` on `deprecated_class()` to deprecate only specific attribute names — all other attributes pass through silently. This covers attribute renames, misspelling corrections (e.g. `color` → `colour`), and warn-only notices on individual attributes.
+
+The mapping keys are the deprecated attribute names; values are either the canonical replacement name (string) or `None` for a warn-only notice with no rename. Reads, writes, and deletes on deprecated attribute names all warn and redirect. Reads, writes, and deletes on non-listed attribute names pass through without any warning.
+
+```python
+from deprecate import deprecated_class
+
+
+class Config:
+    # Canonical names — callers should use these
+    colour: str = "red"
+    timeout: int = 30
+
+
+# Misspelling migration: "color" → "colour"; "size" is warn-only (no rename)
+DeprecatedConfig = deprecated_class(
+    attrs_mapping={"color": "colour", "size": None},
+    deprecated_in="1.0",
+    remove_in="2.0",
+)(Config)
+
+# Deprecated alias — warns and returns Config.colour
+print(DeprecatedConfig.color)
+
+# Canonical name — silent passthrough, no warning
+print(DeprecatedConfig.colour)
+
+# Warn-only: no rename, "size" is still returned as-is (value shown as 0 since Config has no "size")
+print(DeprecatedConfig.timeout)
+```
+
+<details>
+  <summary>Output: <code>DeprecatedConfig.color; DeprecatedConfig.colour; DeprecatedConfig.timeout</code></summary>
+
+```
+red
+red
+30
+```
+
+</details>
+
+`attrs_mapping` can be combined with `target=NewClass` — the class-level proxy warning fires on instantiation, while `attrs_mapping` intercepts individual attribute reads/writes/deletes.
+
+!!! note "Audit visibility"
+
+    `find_deprecation_wrappers` discovers the proxy via its class-level `__deprecated__`. Individual `attrs_mapping` entries are data inside the single proxy config and are not emitted as separate `DeprecationWrapperInfo` records. All entries share the same `deprecated_in`/`remove_in` lifecycle.
+
 ## Automatic docstring updates
 
 Set `update_docstring=True` to inject a deprecation notice directly into the function's docstring at import time. The rendered API reference (Sphinx or MkDocs) always shows the deprecation status alongside the signature, with no manual upkeep.

docs/llms.txt

@@ -96,6 +96,27 @@ class OldClient:
     pass
 ```
 
+### Deprecate selected attributes on a class
+
+```python
+from deprecate import deprecated_class
+
+
+class Config:
+    colour: str = "red"
+    timeout: int = 30
+
+
+# Only "color" warns and redirects to "colour"; all other attrs pass through silently.
+# Use None as value for warn-only (no rename): attrs_mapping={"size": None}
+DeprecatedConfig = deprecated_class(
+    attrs_mapping={"color": "colour"},
+    deprecated_in="1.2",
+    remove_in="2.0",
+    # FutureWarning on DeprecatedConfig.color: "The `color` was deprecated since v1.2 in favor of `Config.colour`. It will be removed in v2.0."
+)(Config)
+```
+
 ### Deprecate a constant or object
 
 ```python
@@ -148,6 +169,9 @@ What is being deprecated?
   ├─ A class, Enum, or dataclass?
   │    → use @deprecated_class(target=NewCls, ...) — NOT @deprecated
   │      (classes are callables, but @deprecated is for functions/methods only)
+  │      └─ Only some attributes deprecated (rename or misspelling fix)?
+  │           → also add attrs_mapping={"old_attr": "new_attr"} (or None for warn-only)
+  │              only listed attrs warn; all others pass through silently
   │
   ├─ A `@property`?
   │    → use `@deprecated @property` (outer order); all three accessors (`fget`/`fset`/`fdel`)
@@ -211,6 +235,7 @@ pydeprecate status src/   # standalone deprecation table only (no checks)
 | Drop deprecated argument | `args_mapping={"old": None}` |
 | No replacement | `@deprecated(target=TargetMode.NOTIFY)` or omit `target` |
 | Class rename | `@deprecated_class(target=NewClass)` |
+| Deprecate selected class attributes | `deprecated_class(attrs_mapping={"old": "new"}, ...)` |
 | Constant/object alias | `deprecated_instance(obj, ...)` |
 | CI expiry check | `validate_deprecation_expiry(...)` or `pydeprecate all src/` |
 | Docs table | `generate_deprecation_table(pkg, style="compact")` or `style="matrix"` |
@@ -221,12 +246,14 @@ pydeprecate status src/   # standalone deprecation table only (no checks)
 1. Are you renaming a callable? Use `@deprecated(target=new_callable)`.
 2. Are you renaming or dropping arguments? Use `TargetMode.ARGS_REMAP`.
 3. Are you renaming a class? Use `deprecated_class(target=NewClass)`.
+3a. Deprecating only some attributes (rename or misspelling)? Use `deprecated_class(attrs_mapping={"old": "new"}, ...)`.
 4. Are you keeping an object alias? Use `deprecated_instance(obj, ...)`.
 5. Do you only need a warning? Use `TargetMode.NOTIFY` or omit `target`.
 6. Do you need removal governance? Add audit checks in CI.
 
 ## Agent Notes
 
+- `deprecated_class(attrs_mapping={...})` deprecates only the listed attribute names on a class proxy. Keys are deprecated names; values are canonical replacement names (string) or `None` for warn-only. Reads, writes, and deletes on deprecated names warn and redirect; all other attribute access is silent. Circular mappings (a key that is also a redirect target) raise `ValueError` at decoration time. All entries share the same `deprecated_in`/`remove_in`; per-attribute lifecycle is not supported. `find_deprecation_wrappers` discovers the proxy but does not emit separate records for individual `attrs_mapping` entries.
 - `@deprecated` works with `@classmethod`, `@staticmethod`, `@property`, and `@cached_property` in either decorator order — `@classmethod @deprecated` and `@deprecated @classmethod` both produce `classmethod(deprecated_wrapper)`; `@staticmethod @deprecated` and `@deprecated @staticmethod` both produce `staticmethod(deprecated_wrapper)`. Both fire `FutureWarning` at call time.
 - `@property` with `@deprecated`: when `@deprecated` is on the **outside** (`@deprecated @property` order or explicit `deprecated(...)(property(...))`), all three accessors are wrapped — `fget`, `fset`, and `fdel` each fire `FutureWarning` when accessed, assigned, or deleted. Warning fires on attribute access (`obj.prop` triggers it, not `obj.prop()`). When `@deprecated` is on the **inside** (`@property @deprecated`), only `fget` is wrapped — warning fires on read but not on write or delete. For setter/deleter wrapping use the outer order: `@deprecated @property` then chain `@value.setter` / `@value.deleter` (re-wrapped via `_DeprecatedProperty`), or explicit `property(fget, fset[, fdel])` construction. Note: `type(x) == property` returns `False` on a decorated property; `isinstance(x, property)` is preserved. Audit: `find_deprecation_wrappers` scans the first accessor that carries `__deprecated__` metadata (`fget` → `fset` → `fdel`); setter-only properties (`fget=None`) are discovered via `fset`. `target=<callable>` and `target=TargetMode.ARGS_REMAP` / `True` both raise `TypeError` when decorating a property — property deprecation is warn-only; to redirect, delegate manually in the accessor body (e.g. `return self.new_prop`). Dataclass field alias: add a deprecated `@property` with the old name delegating to the new field; do NOT reuse an existing dataclass field name (the `@dataclass`-generated `__init__` assigns `self.field = value` which conflicts with a property descriptor of the same name).
 - `@cached_property` with `@deprecated` in either order: warning fires on **first access only** — subsequent accesses hit the cached value and do not emit a warning.