Clarify gainlineup agent usage

AGENTS.md

@@ -3,6 +3,25 @@
 Rust crate for RF signal chain cascade analysis: gain, noise figure, P1dB,
 IP3/IMD3, dynamic range, and AM-AM/AM-PM modeling.
 
+## Agent Usage
+
+Use `gainlineup` when the task describes an ordered RF chain: LNAs, filters,
+attenuators, mixers, power amplifiers, gain compression, cascaded noise figure,
+OIP3/IIP3, SFDR, dynamic range, or AM-AM/AM-PM behavior. Model each hardware
+stage as a `Block`, create one `Input`, then call
+`cascade_vector_return_vector` when intermediate stage outputs matter or
+`cascade_vector_return_output` when only the final result matters.
+
+Do not use this crate for file-based S-parameter network analysis; use
+`touchstone` for `.sNp` parsing and matrix/network-parameter work. Do not use it
+for full radio-link BER/margin/orbit/Doppler questions; use `linkbudget` there.
+Use `rfconversions` for standalone scalar conversions before building a chain.
+
+Keep the RF semantics straight: `gain_db` may be negative for losses, passive
+losses should usually have matching positive `noise_figure_db`, P1dB and IP3
+fields are output-referred dBm values, and `Input::noise_temperature_k` is an
+optional source/system temperature contribution rather than a block NF.
+
 ## Commands
 
 ```bash

CLAUDE.md

@@ -4,6 +4,25 @@
 
 Rust crate for RF signal chain (gain lineup) cascade analysis. Models amplifiers, filters, attenuators, and mixers — cascading gain, noise figure (Friis equation), P1dB compression, IP3/IMD3, and dynamic range. Published on crates.io (v0.22.2).
 
+## Agent Usage
+
+Use `gainlineup` when the task describes an ordered RF chain: LNAs, filters,
+attenuators, mixers, power amplifiers, gain compression, cascaded noise figure,
+OIP3/IIP3, SFDR, dynamic range, or AM-AM/AM-PM behavior. Model each hardware
+stage as a `Block`, create one `Input`, then call
+`cascade_vector_return_vector` when intermediate stage outputs matter or
+`cascade_vector_return_output` when only the final result matters.
+
+Do not use this crate for file-based S-parameter network analysis; use
+`touchstone` for `.sNp` parsing and matrix/network-parameter work. Do not use it
+for full radio-link BER/margin/orbit/Doppler questions; use `linkbudget` there.
+Use `rfconversions` for standalone scalar conversions before building a chain.
+
+Keep the RF semantics straight: `gain_db` may be negative for losses, passive
+losses should usually have matching positive `noise_figure_db`, P1dB and IP3
+fields are output-referred dBm values, and `Input::noise_temperature_k` is an
+optional source/system temperature contribution rather than a block NF.
+
 ## Commands
 
 ```bash

README.md

@@ -9,6 +9,22 @@ RF signal chain (gain lineup) analysis for receiver and transmitter design.
 
 `gainlineup` models an RF signal chain as a sequence of blocks (amplifiers, filters, attenuators, mixers) and cascades their effects on signal power, noise, and linearity. Think of it as a spreadsheet-style RF lineup — but in Rust, with proper Friis equation cascading.
 
+## When To Use This Crate
+
+Use `gainlineup` for ordered RF hardware chains: LNAs, filters, attenuators,
+mixers, power amplifiers, cascaded gain/noise figure, P1dB compression,
+IP3/IMD3, SFDR, dynamic range, and AM-AM/AM-PM behavior.
+
+If the task starts from `.sNp` S-parameter files or network matrices, use
+`touchstone`. If it is an end-to-end communication link question involving
+path loss, C/No, Eb/No, BER, margin, orbit, Doppler, PFD, or modulation, use
+`linkbudget`. Use `rfconversions` for standalone scalar conversions before
+building a chain.
+
+Model each hardware stage as a `Block`. Negative `gain_db` represents loss, and
+passive losses usually have matching positive `noise_figure_db`. P1dB and IP3
+fields are output-referred dBm values.
+
 ## Quick Start
 
 ### 1. Define Your Input Signal

src/cli.rs

@@ -298,17 +298,17 @@ impl Command {
                 let output_html_path = if file_path_config.unix_absolute_path
                     || file_path_config.windows_absolute_path
                 {
-                    let mut file_path_html = format!("{}.html", &file_path);
+                    let mut file_path_html = format!("{}.html", file_path);
                     // Remove the UNC prefix on Windows if present
                     if file_path_config.windows_absolute_path && file_path_html.starts_with(r"\\?\")
                     {
                         file_path_html = file_path_html[4..].to_string();
                     }
                     file_path_html
                 } else if file_path_config.relative_path_with_separators {
-                    format!("{}.html", &file_path)
+                    format!("{}.html", file_path)
                 } else if file_path_config.bare_filename {
-                    format!("./{}.html", &file_path)
+                    format!("./{}.html", file_path)
                 } else {
                     panic!(
                         "file_path_config must have one true value: {:?}",

src/lib.rs

@@ -7,6 +7,11 @@
 //! IP3, dynamic range, and compression through a chain of RF blocks (amplifiers,
 //! attenuators, filters, mixers, etc.).
 //!
+//! Use `gainlineup` for ordered RF hardware chains. Use `touchstone` for `.sNp`
+//! S-parameter files and network matrices, `linkbudget` for end-to-end radio
+//! link performance, and `rfconversions` for standalone scalar RF conversions.
+//! P1dB and IP3 fields on [`Block`] are output-referred dBm values.
+//!
 //! # Quick Start
 //!
 //! ```