@xgent-ai/skills 0.7.5 → 0.7.6

package/skills/rust/references/{chapter_02.md → clippy-and-linting.md}

@@ -1,6 +1,8 @@
-# Chapter 2 - Clippy and Linting Discipline
+# Clippy and Linting Discipline
 
-Be sure to have `cargo clippy` installed with your rust compiler, run `cargo clippy -V` in your terminal for a rust project and you should get a line like `clippy 0.1.xx (<hash> <date>)`, whose minor version tracks your `rustc`. If terminal fails to show a clippy version, please run the following code `rustup update && rustup component add clippy`.
+Check `cargo clippy -V` using the project's pinned toolchain. If the component is missing,
+report it or use the project's authorized setup procedure; do not update the toolchain
+as a side effect of linting.
 
 Clippy documentation can be found [here](https://doc.rust-lang.org/clippy/usage.html).
 
@@ -22,8 +24,8 @@ $ cargo clippy --all-targets --all-features --locked -- -D warnings
 ```
 
 * `--all-targets`: checks library, tests, benches and examples.
-* `--all-features`: checks code for all features enabled, auto solves conflicting features.
-* `--locked`: Requires `Cargo.lock` to be up-to-date, can be solved with `$ cargo update`.
+* `--all-features`: enables every feature; it does not solve conflicts. Run the supported feature sets separately if they cannot coexist.
+* `--locked`: requires the existing lockfile to remain unchanged. Investigate failures instead of running a broad `cargo update`.
 * `-D warnings`: treats warnings as errors
 
 Potential additions elements to add:
@@ -55,7 +57,12 @@ Potential additions elements to add:
 
 * You **truly understand** why the warning happens and you have a reason why it is better that way.
 * You **document** why it is being ignored.
-* ❗ Don't use `allow`, but `expect`, it will give a warning in case the lint is not true anymore, `#[expect(clippy::lint_something)]`.
+* Prefer `#[expect(clippy::lint_something, reason = "...")]` on Rust 1.81+, which warns when the lint no longer fires. Older MSRVs require a narrow `#[allow(...)]` with a reason in a comment.
+
+The `expect` examples below require Rust 1.81+. See the
+[Rust 1.81 release notes](https://blog.rust-lang.org/2024/09/05/Rust-1.81.0/).
+Enforce `-D warnings` in CI rather than introducing blanket `#![deny(warnings)]` in
+source, which can break downstream builds when a new compiler adds warnings.
 
 ### Example:
 
@@ -83,12 +90,14 @@ enum Message {
 
 Sometimes Clippy complains even when your code is correct, in those cases there are two solutions:
 1. Try to refactor the code, so it improves the warning.
-2. **Locally** override the lint with `#[expect(clippy::lint_name)]` and a comment with the reason.
+2. **Locally** override the lint with `#[expect(clippy::lint_name)]` and a reason, or a justified `#[allow]` when the MSRV predates 1.81.
 3. Avoid global overrides, unless it is core crate issue, a good example of this is the Bevy Engine that has a set of lints that should be allowed by default.
 
 ## 2.5 Configure workspace/package lints
 
-In your `Cargo.toml` file it is possible to determine which lints and their priorities over each other. In case of 2 or more conflicting lints, the higher priority one will be chosen. Example configuration for a package:
+Cargo lint tables require 1.74+; see the [Cargo manifest reference](https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section).
+Preserve compatible crate attributes on older toolchains. In `Cargo.toml`, give broad
+groups lower priorities so specific lints can override them. Example for a package:
 
 ```toml
 [lints.rust]
@@ -96,10 +105,10 @@ future-incompatible = "warn"
 nonstandard_style = "deny"
 
 [lints.clippy]
-all = { level = "deny", priority = 10 }
-redundant_clone = { level = "deny", priority = 9 }
-manual_while_let_some = { level = "deny", priority = 4 }
-pedantic = { level = "warn", priority = 3 }
+all = { level = "deny", priority = -1 }
+redundant_clone = "deny"
+manual_while_let_some = "deny"
+pedantic = { level = "warn", priority = -1 }
 ```
 
 And for a workspace:
@@ -110,8 +119,10 @@ future-incompatible = "warn"
 nonstandard_style = "deny"
 
 [workspace.lints.clippy]
-all = { level = "deny", priority = 10 }
-redundant_clone = { level = "deny", priority = 9 }
-manual_while_let_some = { level = "deny", priority = 4 }
-pedantic = { level = "warn", priority = 3 }
+all = { level = "deny", priority = -1 }
+redundant_clone = "deny"
+manual_while_let_some = "deny"
+pedantic = { level = "warn", priority = -1 }
 ```
+
+Each member opts into workspace lint settings with `[lints]` and `workspace = true`.

package/skills/rust/references/{chapter_01.md → coding-idioms.md}

@@ -1,4 +1,8 @@
-# Chapter 1 - Coding Styles and Idioms
+# Coding Styles and Idioms
+
+Read for everyday ownership, control flow, imports and extraction decisions. Public
+signature conventions belong in [API design](api-design.md); queued actions and tree
+traversal belong in [behavioral patterns](behavioral-patterns.md).
 
 ## 1.1 Borrowing Over Cloning
 
@@ -44,6 +48,27 @@ let user = String::from("foo");
 process(&user);
 ```
 
+### Resolve borrowing friction before copying
+
+First bind a temporary to a named local or shorten the borrow with a block. Split a
+complex expression into intermediate values so the conflicting borrow is visible.
+To move a field out of `&mut self`, consider `mem::take`, `mem::replace` or `Option::take`
+instead of cloning it. Restructure ownership only when it improves the design; a
+deliberate independent copy can be clearer than a large refactor.
+
+Take owned `T` when storing or consuming an input, `&T` when reading it, and `&mut T`
+when mutating it in place. Prefer `Option<&T>` to `&Option<T>` when only the inner value
+matters. Use `AsRef<Path>` or `IntoIterator` for library APIs when that flexibility helps
+callers; a concrete slice is often enough for application code.
+
+Use `Rc`/`Arc` for actual shared ownership, and interior mutability only when mutation
+must happen through shared access. Prefer owned fields when borrowing would unnecessarily
+spread lifetimes through containers; retain borrowed views when they express the design.
+
+Split disjoint state when it clarifies ownership rather than adding wrappers solely to
+silence a borrow error. For mixed closure captures, bind selected clones/borrows in a
+block and then use a `move` closure; borrowed captures must still outlive their use.
+
 ### ❌ Avoid redundant cloning:
 ```rust
 fn process_string(name: String) {
@@ -78,7 +103,7 @@ let new_num = increment(num); // `num` still usable after this point
 * The struct **represents a "plain data object"**, without resourcing to ownership (no heap allocations. Example: `Vec` and `Strings`).
 * ❗**The type does not also implement `Iterator`.** Even if every field is `Copy`, never put `Copy` and `Iterator` on the same type (see [§1.5](#15-iterator-iter-vs-for)).
 
-❗**Rust Arrays are stack allocated.** Which means they can be copied if their underlying type is `Copy`, but this will be allocated in the program stack which can easily become a stack overflow. More on [Chapter 3 - Stack vs Heap](./chapter_03.md#33-stack-vs-heap-be-size-smart)
+❗**Rust Arrays are stack allocated.** Which means they can be copied if their underlying type is `Copy`, but this will be allocated in the program stack which can easily become a stack overflow. More on [Stack vs Heap](./performance.md#33-stack-vs-heap-be-size-smart)
 
 For reference, each primitive type size in bytes:
 
@@ -280,6 +305,10 @@ x
 
 ## 1.5 Iterator, `.iter` vs `for`
 
+Use short pipelines for transformations and explicit loops for substantial side effects
+or branching. `Option` supplies zero/one items to `chain` or `extend`; use `if let` for a
+plain branch. Collect fallible items into `Result` to stop at the first error.
+
 First we need to understand a basic loop with each one of them. Let's consider the following problem, we need to sum all even numbers between 0 and 10 incremented by 1:
 
 * `for`:
@@ -361,7 +390,7 @@ for value in vec.iter().enumerate()
 
 Well-written Rust code, with expressive types and good naming, often speaks for itself. Many high-quality codebases thrive on **few or no comments** - and that is a good thing. Where code alone isn't enough (performance quirks, external constraints, non-obvious tradeoffs), a concise comment prevents hours of head-scratching.
 
-The idiom that belongs in *this* chapter is the structural one: **when a comment wants to narrate a function, split the function instead**. For everything else about comments - what makes one good or bad, `SAFETY:`/`CONTEXT:` prefixes, why "living documentation" in comments is a myth, and turning `TODO`s into issues - see [Chapter 8](./chapter_08.md), which owns that topic end to end.
+The idiom that belongs in *this* chapter is the structural one: **when a comment wants to narrate a function, split the function instead**. For everything else about comments - what makes one good or bad, `SAFETY:`/`CONTEXT:` prefixes, why "living documentation" in comments is a myth, and turning `TODO`s into issues - see [Documentation](./documentation.md), which owns that topic end to end.
 
 ### ✅ Breaking up long functions over commenting them
 
@@ -409,10 +438,17 @@ Let **structure** and **naming** replace commentary, and enhance its documentati
 
 > ❗ Splitting is about **naming and clarity**, not deduplication. Before extracting a helper to remove *duplicated* lines, check [§1.8](#18-when-to-extract-a-function-and-when-not-to).
 
-> Doc-comments and doc-testing, `///` and `//!`, are covered in [Chapter 8 - Comments vs Documentation](./chapter_08.md).
+> Doc-comments and doc-testing, `///` and `//!`, are covered in [Comments vs Documentation](./documentation.md).
 
 ## 1.7 Use Declarations - "imports"
 
+Prefer explicit imports and re-exports; tests, enum variants and established framework
+preludes are legitimate exceptions. Avoid adding a catch-all prelude. Scope rarely used
+trait imports locally when clearer, qualify free functions when it reveals meaning
+(`mem::take`, `fs::read`), and retain qualifiers/aliases for ambiguous names (`io::Error`).
+Follow the project's pinned formatter/config; keep skips narrow and justified rather
+than introducing unrelated regrouping or requiring nightly formatting.
+
 Different languages have different ways of sorting their imports, in the Rust ecosystem the [standard way](https://github.com/rust-lang/rustfmt/issues/4107) is:
 
 - `std` (`core`, `alloc` would also fit here).
@@ -472,9 +508,24 @@ group_imports = "StdExternalCrate"
 
 > ❗ `group_imports` and `imports_granularity` are **nightly-only** rustfmt options - still unstable as of 1.96. On stable they are ignored with the warning *"can't set `group_imports = StdExternalCrate`, unstable features are only available in nightly channel"*, so the grouping only applies when you run `cargo +nightly fmt`.
 
+### Module and implementation clarity
+
+- Group modules by responsibility or use case. Name leaf modules after their primary
+  concept; parent modules usually organize and re-export. Preserve established layout
+  and public paths during unrelated edits.
+- Name significant constants and explain their origin/effect. Add type annotations when
+  `into`, `parse` or `collect` obscures intent; bind long expressions to meaningful locals.
+  For non-exhaustive enums, handle known relevant variants explicitly and include a fallback.
+- After mutable setup, a binding can be rebound without `mut` to make its read-only
+  phase explicit. Use `format!` for readable interpolation and `write!`/`push_str` for
+  appending to an existing string.
+- Use the project's structured telemetry with named fields and redacted sensitive data.
+  Preserve a CLI's intended stdout/stderr protocol; diagnostics should not corrupt it.
+  Measure hot logging costs through [performance](performance.md).
+
 ## 1.8 When to Extract a Function (and When Not To)
 
-This chapter ([§1.6](#-breaking-up-long-functions-over-commenting-them)) and [Chapter 8](./chapter_08.md#85-replace-comments-with-code) recommend splitting long functions and replacing narrative comments with named helpers. That advice is about **naming and clarity** -- it is *not* a license to hunt down every repeated line. Extraction has a cost: every helper adds indirection, and a **wrong abstraction is much harder to remove than a little duplication**.
+This chapter ([§1.6](#-breaking-up-long-functions-over-commenting-them)) and [Documentation](./documentation.md#85-replace-comments-with-code) recommend splitting long functions and replacing narrative comments with named helpers. That advice is about **naming and clarity** -- it is *not* a license to hunt down every repeated line. Extraction has a cost: every helper adds indirection, and a **wrong abstraction is much harder to remove than a little duplication**.
 
 > "Duplication is far cheaper than the wrong abstraction." -- [Sandi Metz, The Wrong Abstraction](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction)
 
@@ -546,7 +597,7 @@ If you find yourself maintaining an abstraction like `write_entry`, [Sandi Metz'
 ### ❌ Don't extract when:
 * It is **1-2 lines used in fewer than 3 places** -- the helper is pure indirection.
 * The call sites are only *almost* identical, and unifying them requires **flag parameters** or extra branches.
-* The only motivation is **line count**. A single-caller helper pays off when its *name* clarifies intent ([§1.6](#-breaking-up-long-functions-over-commenting-them), [§8.5](./chapter_08.md#85-replace-comments-with-code)) -- not when it merely relocates code.
+* The only motivation is **line count**. A single-caller helper pays off when its *name* clarifies intent ([§1.6](#-breaking-up-long-functions-over-commenting-them), [§8.5](./documentation.md#85-replace-comments-with-code)) -- not when it merely relocates code.
 * You are **guessing** at a future abstraction. Wait for the third usage to reveal its real shape.
 
 ### 🧫 Test code: readability beats DRY
@@ -558,7 +609,7 @@ In tests, be **even more tolerant of duplication**. The Google Testing Blog call
 * **Shared test helpers couple unrelated tests.** Change one behavior and dozens of tests fail at once -- for the helper's sake, not the behavior's.
 
 Where to draw the line:
-* ✅ Share **setup and fixtures** -- a shared setup function or `rstest` cases, as [Chapter 5](./chapter_05.md#51-tests-as-living-documentation) recommends. Constructing a test server twice is boilerplate, not knowledge.
+* ✅ Share **setup and fixtures** -- a shared setup function or `rstest` cases, as [Testing](./testing.md#51-tests-as-living-documentation) recommends. Constructing a test server twice is boilerplate, not knowledge.
 * ❌ Keep each test's **action and assertion inline**, even when they look repetitive across tests.
 
 > 🚨 When in doubt, **prefer duplication**. A duplicated line is trivially fixed later; a wrong abstraction accretes parameters and conditionals, because each maintainer keeps patching it instead of undoing it.

package/skills/rust/references/crates-and-dependencies.md

@@ -0,0 +1,66 @@
+# Crates and Dependencies
+
+Read when changing Cargo manifests, dependencies, features, public crate boundaries or
+`no_std` support.
+
+## Toolchain and layout
+
+- Inspect `rust-version`, edition, toolchain pins, lockfile and CI before choosing new
+  syntax or dependencies. Preserve the supported toolchain; do not upgrade it to make
+  a suggested idiom compile. For new crates, choose an edition compatible with the MSRV.
+- Keep crates focused, but preserve the existing layout during ordinary changes.
+  Split a crate only for a real responsibility or dependency boundary, not because a
+  directory exists or a size threshold was reached. Account for version coordination,
+  build overhead and cross-crate optimization before splitting.
+- Reuse `[workspace.dependencies]` and workspace lint settings when already available;
+  each package must opt into inherited settings. Cargo `[lints]` requires 1.74+; older
+  toolchains need compatible configuration. See [Clippy and linting](clippy-and-linting.md).
+- Prefer explicit startup over hidden pre-`main` constructors. Preserve required
+  platform/framework initialization during ordinary changes.
+
+## Dependency and feature contracts
+
+- Add a dependency only when it earns its compile time, binary size and maintenance
+  cost. Include build scripts and proc macros in that assessment. Follow project
+  version policy; avoid wildcard versions or exact pins without a concrete reason.
+- Preserve and commit application lockfiles. A `--locked` failure is a dependency-state
+  question, not permission to run a broad `cargo update`.
+- Keep features additive: enabling one should not remove or incompatibly change an
+  existing API. Prefer capability names such as `serde`, `std` or `test-util`.
+- Avoid feature-dependent public fields or required trait methods that make combinations
+  incompatible. Respect existing mutually exclusive features and test supported sets
+  separately; `--all-features` does not resolve conflicts.
+- Feature-gate optional integrations when useful, and account for third-party types
+  exposed in signatures. Use `cargo tree --duplicates` to inspect dependency overlap;
+  inspect feature activation and build/proc-macro dependencies too. Do not assume all
+  versions can be unified. Run project audit/license tools when dependency changes
+  call for them; a style guide does not authorize changing the project's license.
+
+## no_std and constrained targets
+
+- Add `no_std` support for a concrete target or caller need. `core` supplies fundamental
+  types; `alloc` adds heap-backed collections and pointers where allocator/target support
+  exists. Check target support for required atomics rather than assuming `Arc` everywhere.
+- Gate std integration additively, commonly with
+  `#![cfg_attr(not(feature = "std"), no_std)]`; use capability names such as `std`/`alloc`.
+  Hashing does not fundamentally require an OS: choose compatible collections, hashers
+  and randomness policy. Use `try_reserve` when allocation failure must be recoverable.
+- Build for the intended target and supported allocator configuration. Document native
+  prerequisites; prefer normal Cargo builds and ship generated files when practical.
+  Binding generation and drift checks belong at the [FFI boundary](unsafe-and-ffi.md).
+
+## Compatibility and validation
+
+- Removing or renaming public items, adding required bounds/methods, adding variants to
+  exhaustive enums, changing constructible public structs, or losing dyn compatibility
+  may break downstream callers. Assess before editing; deprecate and migrate according
+  to the crate's version policy.
+- Check default, no-default and relevant feature combinations when affected. Include
+  supported targets and MSRV checks for changes that can alter compatibility.
+- Prefer the project's existing CI commands over introducing another tool suite.
+  Keep them reproducible locally with supported toolchain pins, detect generated-code
+  drift, and investigate flaky tests rather than deleting their coverage. Report
+  unsupported or untested combinations rather than implying universal coverage.
+- Keep package description, license, repository, authors, keywords and categories
+  accurate; avoid redundant metadata URLs. Document breaking changes and follow the
+  project's release/tag policy. These checks do not authorize tagging or publishing.

package/skills/rust/references/{chapter_08.md → documentation.md}

@@ -1,4 +1,4 @@
-# Chapter 8 - Comments vs Documentation
+# Comments vs Documentation
 
 > Clear code beats clear comments. However, when the why isn't obvious, comment it plainly - or link to where you can read more context.
 
@@ -24,7 +24,8 @@ Use `//` comments (double slashed) when something can't be expressed clearly in
 
 ### ✅ Good comment:
 ```rust
-// SAFETY: `ptr` is guaranteed to be non-null and aligned by caller
+// SAFETY: the caller guarantees src is readable and initialized for len elements,
+// dst is writable for len elements, both are aligned, and the regions do not overlap.
 unsafe { std::ptr::copy_nonoverlapping(src, dst, len); }
 ```
 
@@ -103,7 +104,7 @@ fn save_auth_user(&self) -> Result<PathBuf, MyError> {
 }
 ```
 
-> ❗ Extract when the **name adds meaning** -- not to deduplicate a couple of similar-looking lines. See [Chapter 1, §1.8](./chapter_01.md#18-when-to-extract-a-function-and-when-not-to) for when duplication is the better trade-off.
+> ❗ Extract when the **name adds meaning** -- not to deduplicate a couple of similar-looking lines. See [Coding Idioms, §1.8](./coding-idioms.md#18-when-to-extract-a-function-and-when-not-to) for when duplication is the better trade-off.
 
 ## 8.6 `TODO` should become issues
 
@@ -201,6 +202,32 @@ pub fn add(a: i32, b: i32) -> i32 {
 * ✅ Use `# Panics`, `# Errors` and `# Safety` sections when relevant.
 * Add relevant context to the type.
 
+Document what the signature cannot express: ownership transfer, preconditions, side
+effects and failure modes. Use a concise first-sentence summary and intra-doc links
+such as `` [`Type`] ``. Describe the resulting API, not a journal of the editing process.
+Explain abort behavior when part of the contract. Panic/assertion diagnostics should
+identify the violated invariant without exposing secrets.
+For fallible examples, show `?` rather than `unwrap()` with hidden result scaffolding:
+
+```rust
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let port: u16 = "8080".parse()?;
+/// assert_eq!(port, 8080);
+/// # Ok(())
+/// # }
+/// ```
+```
+
+Run doc tests and `cargo doc --no-deps` for public API changes. New unsafe boundaries
+also need the contract checks in [Unsafe and FFI](unsafe-and-ffi.md).
+Hidden setup can keep examples concise, but assertions in a helper that is never called
+are only compiled, not executed. Ensure behavior demonstrations actually run.
+
+For crate-internal re-exports, consider `#[doc(inline)]` when it improves navigation.
+Do not present foreign implementation details as owned API. `#[doc(hidden)]` hides
+documentation, not access: privacy requires visibility controls.
+
 ### `//!` Module/Crate level Documentation
 
 Use `//!` when you want to document the **purpose of a module or a crate**. It is places at the top of a `lib.rs` or `mod.rs` file, for example `engine/mod.rs`:

package/skills/rust/references/{chapter_04.md → error-handling.md}

@@ -1,4 +1,4 @@
-# Chapter 4 - Errors Handling
+# Errors Handling
 
 Rust enforces a strict error handling approach, but *how* you handle them defines where your code feels ergonomic, consistent and safe - as opposing cryptic and painful. This chapter dives into best practices for modeling and managing fallible operations across libraries and binaries.
 
@@ -27,10 +27,10 @@ fn divide(x: f64, y: f64) -> Result<f64, DivisionError> {
 
 ## 4.2 Avoid `unwrap`/`expect` in Production
 
-Although `expect` is preferred to `unwrap`, as it can have context, they should be avoided in production code as there are smarter alternatives to them. Considering that, they should be used in the following scenarios:
-- In tests, assertions or test helper functions.
-- When failure is impossible.
-- When the smarter options can't handle the specific case.
+This skill reserves `unwrap()` and `expect()` for tests and test helpers. Outside tests,
+propagate failures with `?`, pattern-match explicitly or encode the invariant in a type.
+An assumed-impossible failure is not an exception to this rule. Do not replace an unwrap
+with a panic on ordinary invalid input, I/O failures or lock poisoning.
 
 ### 🚨 Alternative ways of handling `unwrap`/`expect`:
 
@@ -50,7 +50,7 @@ if let Ok(json) = serde_json::from_str(&input) {
     recover_from(&input)
 }
 ```
-* Functions that can have to handle `Option::None` values are recommended to return `Result<T, E>`, where `E` is a crate or module level error, like the examples above.
+* Keep `Option` when absence is normal. Convert `None` to `Result` with `ok_or_else` when the caller needs a reason the operation failed.
 * Lastly `unwrap_or`, `unwrap_or_else` or `unwrap_or_default`, these functions help you create alternative exits to unwrap that manage the uninitialized values.
 
 ## 4.3 `thiserror` for Crate level errors
@@ -76,6 +76,18 @@ pub enum MyError {
 
 ### Error Hierarchies and Wrapping
 
+Public errors implement `std::error::Error` (`Debug` + `Display`) and preserve wrapped
+causes through `source()`; `thiserror` can generate this alongside `From` conversions.
+Expose categories callers can act on, not a single enum of every internal failure.
+A situation-specific struct with private details and public accessors is also valid.
+Keep messages concise (normally lowercase without trailing punctuation), and add
+`Send + Sync + 'static` when required by the API or task boundary. Capture backtraces
+when useful, without forcing the full cause chain/backtrace into `Display`. Use
+`map_err` when a conversion needs context that a meaningful `From` cannot supply.
+
+If a fallible operation consumes input that callers may need to retry, consider returning
+that input in the error. Avoid making callers clone large inputs merely for recovery.
+
 For layered systems the best practice is to use nested `enum/struct` errors with `#[from]`:
 
 ```rust
@@ -181,3 +193,17 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 ```
 
 > Avoid `Box<dyn std::error::Error>` in libraries unless it is really needed
+
+### Cleanup and panic boundaries
+
+Bind RAII guards to a local name (`let _guard = ...`); `let _ = ...` drops the value
+immediately. Offer an explicit `close(self) -> Result<...>` or `finish` for fallible
+cleanup, and keep `Drop` best-effort and non-panicking. Move slow or asynchronous
+teardown into an explicit operation instead of starting detached work from `Drop`.
+Fields already owning resources usually need no redundant custom `Drop`. Cleanup runs
+on ordinary scope exit and unwinding, but cannot guarantee essential work after abort,
+process termination or deliberate forgetting.
+
+Do not use `catch_unwind` to handle ordinary errors; aborting panics cannot be caught.
+For FFI-specific boundaries see [Unsafe and FFI](unsafe-and-ffi.md). Document errors,
+reachable panics and unsafe preconditions in the public API.

package/skills/rust/references/{chapter_06.md → generics-and-dispatch.md}

@@ -1,4 +1,4 @@
-# Chapter 6 - Generics, Dynamic Dispatch and Static Dispatch
+# Generics, Dynamic Dispatch and Static Dispatch
 
 > Static where you can, dynamic where you must
 
@@ -12,7 +12,7 @@ Understanding the trade-offs lets you write faster, smaller and more flexible co
 
 Every programming language has tools for effectively handling the duplication of concepts. In Rust, one such tool is generics: abstract stand-ins for concrete types or other properties. We can express the behavior of generics or how they relate to other generics without knowing what will be in their place when compiling and running the code. 
 
-We use generics to create definitions for items like function signatures or structs, which we can then use with many different concrete data types. Let's first look at how to define functions, structs, enums, and methods using generics. Generics can also be used to implement Type State Pattern and constrain a struct functionality to certain expected types, more on type state on [Chapter 7](./chapter_07.md).
+We use generics to create definitions for items like function signatures or structs, which we can then use with many different concrete data types. Let's first look at how to define functions, structs, enums, and methods using generics. Generics can also be used to implement Type State Pattern and constrain a struct functionality to certain expected types, more on type state on [Type State](./type-state.md).
 
 [Generics by Examples](https://doc.rust-lang.org/rust-by-example/generics.html).
 
@@ -107,9 +107,9 @@ fn all_animals_greeting(animals: Vec<Box<dyn Animal>>) {
 
 ## 6.5 🚨 Trait Objects Ergonomics
 
-* Prefer `&dyn Trait` over `Box<dyn Trait>` when you don't need ownership.
+* Borrow `&dyn Trait` without allocating when ownership is unnecessary; use
+  `Box<dyn Trait>` at a boundary that needs ownership.
 * Use `Arc<dyn Trait>` for shared access across threads.
-* Don't use `dyn Trait` if the trait has methods that return `Self`.
 * **Avoid boxing too early**. Don't box inside structs unless you are sure it'll be beneficial or is required (recursive).
 ```rust
 // ✅ Use generics when possible
@@ -122,12 +122,16 @@ struct Renderer {
     backend: Box<dyn Backend> // Boxing too early
 }
 ```
-* If you must expose a `dyn trait` in a public API, `Box` at the boundary, not internally.
-* **Dyn compatibility**: you can only build `dyn Trait` from a *dyn-compatible* trait. This property used to be called **object safety**; the term was renamed, and current compilers report *"error[E0038]: the trait `Factory` is not dyn compatible"*. A trait qualifies when:
-    * It has **no generic methods**.
-    * It doesn't require `Self: Sized`.
-    * No method returns or takes `Self` by value.
-    * Every method's receiver is one Rust can build a vtable for - `&self`, `&mut self`, `self`, or `self: Box<Self>` / `Rc<Self>` / `Arc<Self>` / `Pin<..>`.
+* **Dyn compatibility** (formerly object safety) applies to the whole trait:
+    * Its supertraits are dyn compatible, it does not require `Self: Sized`, and it has
+      no associated constants or generic associated types.
+    * Dispatchable methods have no type parameters, use `Self` only in their receiver,
+      and have neither `async fn` nor return-position `impl Trait` return types.
+      Supported receivers include references, `Box`, `Rc`, `Arc` and their allowed
+      `Pin` forms; plain by-value `self` is not dispatchable.
+    * Methods outside that contract can require `where Self: Sized`, excluding them
+      from object dispatch while allowing the remaining trait to be dyn compatible.
+      Test the intended `dyn Trait` usage, auto traits and lifetimes.
     ```rust
     // ✅ Dyn compatible
     trait Runnable {
@@ -136,7 +140,20 @@ struct Renderer {
 
     // ❌ Not dyn compatible
     trait Factory {
-        fn create<T>() -> T; // generic methods are not allowed
+        fn create<T>() -> T; // no Self: Sized exemption for this generic function
     }
     ```
     > See the reference on [dyn compatibility](https://doc.rust-lang.org/reference/items/traits.html#dyn-compatibility) for the full rules.
+
+## 6.6 Trait and closure contracts
+
+- Define traits for polymorphism or useful extension methods, not merely to organize
+  functions. Extension traits conventionally use an `Ext` suffix. Keep parameter and
+  lifetime names descriptive when their role is otherwise unclear.
+- Require the calling contract you need: `FnOnce` accepts the widest set of closures
+  when called once; use `FnMut` for repeated mutable calls and `Fn` for shared calls.
+- Keep required trait methods minimal and provide defaults for derivable behavior.
+  Even adding a default method can create downstream method ambiguity; review compatibility.
+- Avoid reflection-shaped designs when an enum or trait expresses the boundary.
+  `type_name` is diagnostic text, not a stable identifier; `Any`/downcasting is an
+  intentional type-erasure boundary with a `'static` requirement.

package/skills/rust/references/macros.md

@@ -0,0 +1,45 @@
+# Macros and Generated APIs
+
+Read when writing or reviewing declarative macros, proc macros or generated Rust APIs.
+
+## Choose generation for a concrete need
+
+Prefer functions, types, traits and ordinary control flow when they express the operation.
+Use `macro_rules!` for useful repetition or declarative syntax, such as keeping one table
+of definitions synchronized. Choose a proc macro when syntax analysis/transformation
+earns its build cost, IDE limitations and diagnostic complexity. A normal example may
+be clearer than a new macro abstraction.
+
+## Preserve the caller's contract
+
+- Make syntax resemble the Rust it produces and expose control-flow effects. Document
+  generated public items and signature transformations; do not hide surprising APIs.
+- Generated items are private unless callers request visibility. Forward attributes
+  such as `cfg`, docs and derives to the intended items, and document any restrictions.
+- Accept ordinary type syntax, including primitive, generic and qualified types. Do not
+  move caller types into an inaccessible generated module or require accidental imports.
+- Keep name resolution hygienic across supported invocation scopes and dependency
+  renaming. In declarative macros, use `$crate` for defining-crate paths where appropriate.
+- Evaluate expression arguments the documented number of times, normally once. Test
+  side effects and borrowing rather than assuming a textual expansion behaves like a call.
+
+## Keep proc macros maintainable
+
+- Keep entrypoints thin and substantial transformation logic in normally testable code.
+  Add a helper crate only when it earns its maintenance cost; tiny macros do not need
+  a prescribed multi-crate architecture.
+- Generated code may need runtime helpers through a hidden re-export. That path remains
+  externally reachable even with `#[doc(hidden)]`; account for visibility, compatibility
+  and renamed dependencies.
+- Exact companion versions and coordinated releases may be necessary when generated
+  code tightly couples to runtime helpers. Do not apply that pinning rule to unrelated
+  dependencies; follow [crate compatibility](crates-and-dependencies.md).
+
+## Verify expansion and diagnostics
+
+Use the project's compile-pass/compile-fail tests (for example, an existing `trybuild`
+suite) to cover accepted syntax and rejected input. Include visibility and attribute
+forwarding, generic/qualified types, supported module/function/nested invocation sites,
+name collisions and renamed dependencies. Verify argument evaluation behavior and
+actionable diagnostics. Inspect expansions when useful; expansion snapshots alone do
+not prove generated code compiles or behaves correctly.

package/skills/rust/references/{chapter_03.md → performance.md}

@@ -1,4 +1,4 @@
-# Chapter 3 - Performance Mindset
+# Performance Mindset
 
 The **golden rule** of performance work:
 
@@ -69,7 +69,7 @@ The result will look like a flame graph where:
 
 > Cloning is cheap... **until it isn't**
 
-In sections [Borrowing over Cloning](./chapter_01.md#11-borrowing-over-cloning) and [Important Clippy lints to respect](./chapter_02.md#23-important-clippy-lints-to-respect) we mentioned the impacts of cloning and the relevant clippy lint [`redundant_clone`](https://rust-lang.github.io/rust-clippy/master/#redundant_clone), so in this section we will explore a bit "when to pass ownership".
+In sections [Borrowing over Cloning](./coding-idioms.md#11-borrowing-over-cloning) and [Important Clippy lints to respect](./clippy-and-linting.md#23-important-clippy-lints-to-respect) we mentioned the impacts of cloning and the relevant clippy lint [`redundant_clone`](https://rust-lang.github.io/rust-clippy/master/#redundant_clone), so in this section we will explore a bit "when to pass ownership".
 
 * 🚨 If you really need to clone, leave it to the last moment.
 
@@ -207,3 +207,26 @@ process(doubled);
 let doubled_iter = items.iter().map(|x| x * 2);
 process(doubled_iter);
 ```
+
+## 3.5 Allocation and throughput after measurement
+
+Measure hot paths with release builds before adding complexity. Reserve capacity when
+the expected size is known, reuse caller-owned buffers where repeated allocation is a
+bottleneck, and batch work to reduce per-item locking. `Box<[T]>`, `Box<str>` or `Arc<str>`
+can suit long-lived immutable data; benchmark conversion and sharing costs too.
+Reusable-buffer APIs must specify clearing versus appending and what remains on failure.
+
+Keep `format!` out of hot logging loops when structured fields suffice; use `write!`
+when appending to an existing buffer. Faster hashers are a workload-specific choice for
+trusted keys, not a default for untrusted input. Allocator changes and `shrink_to_fit`
+need workload evidence rather than automatic application to every collection.
+
+Measure indirection and disabled-event logging costs too; avoid doing formatting or
+allocation work for telemetry that will not be emitted. An alternative global allocator
+is an application decision, not something a library should impose. CPU-specific tuning
+requires a guaranteed deployment baseline; preserve portability of general-purpose builds.
+
+For large or frequently created futures, inspect values held across suspension. Reduce
+retained state or perform immediate setup outside the future only when the change in
+execution timing preserves the contract. Keep CPU work off async workers or split it
+into measured bounded chunks; there is no universal yield interval for every workload.