Project wording fixes

src/projects/annotations.md

@@ -1,36 +1,46 @@
 ## Annotations
 
-Annotations are a powerful feature introduced in Radare2 5.9.6 that allows users to associate cross-project metadata with specific functions. Unlike comments or other metadata that are tied to a specific project or session, annotations are persistent and stored globally. This makes them particularly useful for tracking notes and observations across different projects without needing to worry about manually saving them.
+Annotations are a handy feature introduced in Radare2 5.9.6 that allows users to associate cross-project metadata with specific functions. Unlike comments or other metadata that are tied to a specific project or session, annotations are persistent and stored globally. This makes them particularly useful for tracking notes and observations across different projects without needing to worry about manually saving them.
 
-The annotations are associated with each function and stored in a dedicated cache directory, making them available even after you leave the session. You can think of annotations as a place to store function-specific notes, decompilation output, or other important information that you want to keep handy.
+The annotations are associated with the filename and function address, and it's stored in a dedicated cache directory, making them available even after you leave the session. You can think of annotations as a place to store function-specific notes, decompilation output, or other important information that you want to keep handy.
+
+```
+R2_CACHEDIR=~/.local/share/radare2/cache/
+${R2_CACHEDIR}/ano.${filename}.{func_address}.txt
+```
 
 ### Using the ano
 
 Annotations can be managed using the `ano` command. Below is an overview of the available options:
 
 ```console
 [0x00000000]> ano?
-Usage: ano  [*] # function annotations
-| ano            show or edit annotations for the current function
-| ano-*          remove all annotations of the current file
-| ano*           dump all annotations in `ano=` commands
-| ano=[b64text]  set annotation text in base64 for current function
-| anoe           edit annotation
-| anos           show annotation
-| anol           show the first line of function annotation if any
+Usage: ano  [*] # function anotations
+| ano                show or edit annotations for the current function
+| ano-*              remove all annotations for current file
+| ano-$$             remove annotations for current function
+| ano*               dump all annotations in ano= commands
+| ano=[base64:]text  set anotation text in base64 for current function
+| anoe               edit annotation using cfg.editor
+| anos               show current function annotation
+| anol               display first line of function annotation if any
 [0x00000000]>
 ```
 
 ### Key Features
 
 **Persistent Across Sessions:**
 
-Annotations are stored globally in the `~/.local/share/radare2/cache` directory. This ensures that they are accessible across different sessions, even if the project is closed and reopened later.
+Annotations are stored globally in the XDG cache directory. This ensures that they are accessible across different sessions, even if no project is used.
 
 **Multiline Annotations:**
 
 Annotations can contain multiple lines of text, making them ideal for storing detailed notes, such as decompilation output, comments, or any other observations about a function.
 
+Only the first line of the annotation will be displayed in the disassembly. Take this in mind when writing them to make them look nicer in the disassembly listing.
+
+You can disable this feature by toggling the `e asm.anos` eval variable.
+
 **Cross-Project:**
 
 Since annotations are not tied to any specific project, they can be shared across different projects that analyze the same binary. This is useful when working with multiple teams or revisiting an old analysis.
@@ -73,19 +83,22 @@ To remove all annotations for the current file, you can use the `ano-*` command:
 [0x00000000]> ano-*
 ```
 
-### Annotations in Action: Using Annotations to Cache Decompilation Output
+### Annotations In Action
+
+*Using Annotations to Cache Decompilation Output*
 
 Annotations can also be used to improve efficiency when working with decompiled code. For example, the `-e cache=true` setting in Radare2 enables the caching of decompiled output. This prevents Radare2 from having to re-decompile the same function multiple times, thus saving time during the analysis.
 
 Here's an example of how this works:
 
-1. Decompiling a function in language mode normally requires Radare2 to call the decompiler for each function.
-2. By enabling caching with `-e cache=true`, Radare2 will store the decompilation output in an annotation. The next time you view the same function, the cached annotation will be used instead of calling the decompiler again.
+* Decompiling a function using AI requires consuming tokens or cpu time, which tends to be slow and expensive.
+* By enabling caching with `-e cache=true`, Decai will store the decompilation output in an annotation. The next time you view the same function, the cached annotation will be used instead of calling the decompiler again.
 
 This is particularly helpful when working with large binaries or performing repetitive decompilation tasks.
 
 ```bash
-$ r2 -e cache=true <binary>
+$ r2pm -ci decai # install the decai decompiler
+$ r2 -c 'decai -e cache=true' <binary>
 ```
 
 By leveraging annotations in this way, you can significantly reduce the overhead of reprocessing functions during analysis.

src/projects/challenges.md

@@ -1,6 +1,6 @@
 ## Challenges Managing Projects
 
-Managing metadata during binary analysis is a critical aspect of reverse engineering. Metadata includes function names, comments, analysis flags, decompilation results, and much more. However, there are several inherent challenges that reverse engineering tools need to address to ensure efficient project management. Let's explore some of these challenges:
+Managing metadata during binary analysis is a critical aspect of reverse engineering. Metadata includes function and variable names, comments, analysis flags, decompilation results, and much more. However, there are several inherent challenges that reverse engineering tools need to address to ensure efficient project management. Let's explore some of these challenges:
 
 ### Key Challenges
 
@@ -16,6 +16,12 @@ As tools evolve, their analysis algorithms and metadata formats may change. This
 
 The order in which metadata is stored and loaded is crucial. For example, you cannot name a function before it is analyzed, and any changes to the analysis steps could affect the final outcome. This creates dependencies between analysis steps and metadata storage.
 
+**Metadata Origin**
+
+Some of the patches applied into the file come from the bin parser, like symbol names or reloc patches. But others can be defined by analysis commands or even by user scripts or the user itself. Knowing who created this information is relevant to the project because it helps understand the consequences of each action r2 performs in the binary.
+
+All tools available out there have no way to correlate consequences with the trigger that is the origin of the metadata created.
+
 **Impact of Analysis Order**
 
 The sequence in which analysis steps are performed can significantly impact the final results. Skipping or reordering analysis commands can lead to different interpretations of the binary.
@@ -46,6 +52,8 @@ User-specific settings can influence how analysis and metadata are registered. F
 
 Metadata must be updated incrementally during the analysis. Each change to the analysis (e.g., renaming a function, adding a comment) must be stacked properly, and failure to do so can lead to inconsistency or corruption of the project state.
 
+Timestamping every single element in memory may help creating a proper log to do/undo every action you perform inside r2. But this is currently not possible for all operations, and also note that different io layers can be swapped at any time breaking the whole scope of the data.
+
 ### Why These Challenges Matter
 
 Looking at the challenges listed above, it's clear that managing reverse engineering projects is a complex task. Each of these issues can affect the accuracy, consistency, and efficiency of the analysis process. This complexity is magnified when working in collaborative environments or when dealing with long-term projects that may span multiple tool versions.

src/projects/handmade.md

@@ -6,7 +6,7 @@ When you need full control and complete flexibility over your project metadata,
 * Set the base address.
 * Configure the memory layout.
 * Run specific analysis commands.
-* Have full control on the steps
+* Add comments, set dwords, rename functions, ..
 
 Note that having full control on the commands you run is important in a variety os sutations (read the section on challenges for more details).
 
@@ -60,7 +60,7 @@ And to reload them:
 
 You can apply this same principle to comments (`CC*`), function names (`afn*@@F`), and more.
 
-### Default Script Behavior
+### Default Script Example
 
 If you save an `.r2` script in the same directory as the binary, Radare2 will prompt you to run it upon opening the binary. This can save time by eliminating the need to use the `-i` flag: