Johannes's CR

Author: naftali-g

docs/cvl/linking.md

@@ -3,10 +3,10 @@
 ===========
 
 The `links` block allows you to declare contract linking directly in your CVL
-specification, replacing the {ref}`--link` and {ref}`--struct_link` CLI flags.
-Each entry in the `links` block tells the Prover that a particular storage
-location holding an address should be resolved to a specific contract instance
-in the {term}`scene`.
+specification, replacing the {ref}`--link` and {ref}`--struct_link` conf file
+attributes. Each entry in the `links` block tells the Prover that a particular
+storage location holding an address should be resolved to a specific contract
+instance in the {term}`scene`.
 
 The `links` block supports linking simple scalar fields, struct fields, array
 elements, mapping entries, immutable variables, and arbitrary nesting of these.
@@ -52,7 +52,7 @@ Basic Linking
 
 The simplest form of linking maps a storage variable that holds an address to a
 contract instance in the scene.  This is equivalent to using the {ref}`--link`
-CLI flag.
+conf file attribute.
 
 Given a contract with a storage variable `token` of type `address` (or a
 contract type like `IERC20`):

docs/prover/cli/options.md

@@ -1939,6 +1939,13 @@ _Configuration file_
 <contract>:<slot>=<address>
 ```
 
+```{note}
+The recommended approach is to declare linking inline in your spec using a
+{ref}`links block <linking>`, which provides type checking, precise struct
+paths, and support for arrays, mappings, and wildcards. The `links` block and
+`--link` flag cannot be used together in the same Prover run.
+```
+
 **What does it do?**
 Links a slot in a contract with another contract.
 
@@ -1966,13 +1973,6 @@ _Configuration file_
 ]
 ```
 
-```{note}
-You can also declare linking inline in your spec using a {ref}`links block <linking>`,
-which provides type checking, precise struct paths, and support for arrays,
-mappings, and wildcards.  The `links` block and `--link` flag cannot be used
-together for the same contract.
-```
-
 (--optimistic_contract_recursion)=
 ## `optimistic_contract_recursion`