From d397ac7427f8bf72b4f8f579de7b74cd52b17e40 Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Sat, 24 Oct 2026 04:18:15 +0800
Subject: [PATCH] docs(native): clarify Darwin runtime breakpoint names

---
 .../references/native-and-artifacts.md                 |  4 ++++
 docs/native-investigation.md                           | 10 ++++++++++
 src/domain/native/nativeCallObservation.ts             |  2 +-
 3 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md
index 70b0afdff3..ba4c391e45 100644
--- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md
+++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md
@@ -250,6 +250,10 @@ run, use `observe_native_calls` with explicit breakpoints and a bounded
 `duration_ms`/`max_events`. It launches a new process under LLDB, so the target
 runs and may change files or use the network. Hardened-runtime targets need the
 `get-task-allow` entitlement.
+Function breakpoints use exact LLDB runtime names: a Darwin C `_main` static symbol
+may be `main` at runtime. REA does not translate names. Set `module` to the image
+file name when selecting that image only; otherwise loaded system images also
+match. Inspect retained locations and module paths before attributing a call.
 
 Use `binary_session` with no arguments to check the open target, selected
 provider, and alignment. Its default `result.tool_availability` carries a
diff --git a/docs/native-investigation.md b/docs/native-investigation.md
index 84e2e1cc79..e43dd12626 100644
--- a/docs/native-investigation.md
+++ b/docs/native-investigation.md
@@ -765,6 +765,16 @@ missing LLDB. `duration_ms` controls the later target observation window.
 rea observe-native-calls /Applications/Example.app '{"breakpoints":[{"kind":"objc-method","class_name":"NSURLSession","selector":"dataTaskWithRequest:completionHandler:"},{"kind":"function","name":"open","module":"libsystem_kernel.dylib"}],"duration_ms":5000,"backtrace_frames":4}' --json
 ```
 
+Function names select LLDB runtime symbols. On Darwin, a C function reported as
+`_main` by `inspect_macho` or `nm` can resolve as `main` in LLDB. REA preserves the
+exact selected name; it does not remove underscores or translate static names.
+Use `{"kind":"function","name":"main","module":"Example"}` to limit that
+runtime symbol to the executable image named `Example`, then inspect the reported
+locations and image paths. Omitting `module` deliberately matches every loaded
+image, including system libraries. A match outside the executable is valid for
+that request and does not by itself make coverage partial. This C naming example
+does not establish a translation rule for Swift, C++ or other mangled symbols.
+
 Each event is an observation: thread, image, symbol, load and file address,
 the raw integer argument registers, optional caller frames and, for an
 Objective-C method, the selector read from `_cmd` and the receiver's dynamic
diff --git a/src/domain/native/nativeCallObservation.ts b/src/domain/native/nativeCallObservation.ts
index cf8d8f0b1c..44ba3e6a60 100644
--- a/src/domain/native/nativeCallObservation.ts
+++ b/src/domain/native/nativeCallObservation.ts
@@ -19,7 +19,7 @@ const functionBreakpoint = {
   name: nativeString
     .min(1)
     .describe(
-      "Exact symbol name, such as `open`, a C++ or mangled Swift symbol, or `-[NSString length]`.",
+      "Exact LLDB runtime symbol name, such as `open`, a C++ or mangled Swift symbol, or `-[NSString length]`. Darwin C symbol-table `_main` may be exposed by LLDB as `main`; REA preserves the selected name without translating it.",
     ),
 };