From 0929fa42098b1d8fb2276e66ebd4a46708faaaea Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Sat, 24 Oct 2026 02:58:57 +0800
Subject: [PATCH] docs(architecture): clarify map scope and provider wiring

Describe the diagram as selected layer owners and dependency paths. Link the canonical composition factories and direct Frida/Cutter entry wiring, and add the omitted Kuna deep-provider node and its verified dependencies.

Documentation checks cover source links and generated facts; no exhaustive directory inventory or new provider capability is claimed.

Fixes #6901
---
 CONTRIBUTING.md           | 16 ++++++++++++----
 README.md                 |  2 +-
 docs/architecture.mermaid |  8 +++++++-
 3 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bfd27028b9..19f87f919b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,10 +10,18 @@ and maintenance cost. Keep cosmetic polish with useful fixes; confusing or
 incorrect user instructions warrant standalone corrections. Collect other
 cosmetic-only suggestions in an issue rather than separate PRs.
 
-For capability organization and provider composition, use the
-[architecture map](docs/architecture.mermaid). Production factories in
-`src/composition/` construct fresh providers without starting engines or acquiring
-targets; optional adapter failures must preserve successful peers. Run
+For selected architectural owners and dependency paths, use the
+[architecture map](docs/architecture.mermaid). It is not a complete directory or
+import inventory. For current provider wiring, start with
+[`src/composition/binary.ts`](src/composition/binary.ts) for deep candidates and
+the other `src/composition/` factories for tool services, including
+[`gpu.ts`](src/composition/gpu.ts) and [`model.ts`](src/composition/model.ts).
+Live Frida and Cutter adapters are constructed directly in
+[`src/cli/fridaCommands.ts`](src/cli/fridaCommands.ts),
+[`src/cli/cutterCommands.ts`](src/cli/cutterCommands.ts), and
+[`src/server/createServer.ts`](src/server/createServer.ts).
+Production factories construct fresh providers without starting engines or
+acquiring targets; optional adapter failures must preserve successful peers. Run
 `npm run verify:test-discovery` after adding or moving tests. Resolved import
 boundaries are checked by `npm run verify:module-boundaries`, included in lint.
 
diff --git a/README.md b/README.md
index e6e718e3ab..83ac32e50f 100644
--- a/README.md
+++ b/README.md
@@ -399,7 +399,7 @@ to improve the code or docs.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
 [testing](docs/testing.md) for verification lanes, and the
-[architecture map](docs/architecture.mermaid) for the project structure.
+[architecture map](docs/architecture.mermaid) for selected layers and dependency paths.
 
 ## License
 
diff --git a/docs/architecture.mermaid b/docs/architecture.mermaid
index 962bb0f1ba..ddb1d785b4 100644
--- a/docs/architecture.mermaid
+++ b/docs/architecture.mermaid
@@ -1,4 +1,6 @@
 graph TD
+    %% Selected layer owners and dependency/wiring paths, not a directory or import inventory.
+    %% Current deep-provider candidates are wired in src/composition/binary.ts.
     subgraph "Entry Points"
         CLI["src/cli.ts + src/cli/<br/>One-shot CLI adapter<br/>setup, diagnostics, analysis, decompilation"]
         MAIN["src/main.ts + src/main/<br/>MCP server adapter: stdio default, streamable HTTP opt-in<br/>config, session, process lifetime"]
@@ -25,7 +27,7 @@ graph TD
         JS_RECON["src/application/javascript/ + src/artifacts/javascript/<br/>JavaScript artifact reconstruction<br/>directory/ASAR reads<br/>AST-only bundle projection"]
     end
 
-    subgraph "Provider Layers"
+    subgraph "Provider Layers (selected adapters)"
         PROVIDER_OWNERS["src/providers/<br/>shared deferred client and inspection owners<br/>exact cleanup retry and attributed failures"]
         PWNTOOLS["src/native/pwntools/ + src/native/pwndbg/<br/>BYO offline ELF/core adapters<br/>owned snapshots/Python and optional core-only GDB<br/>unchanged upstream parsers, ABI structures and mapping API"]
         WASM["src/wasm/<br/>caller-supplied WABT; immutable artifact inspection<br/>owned process supervision and retryable workspace cleanup"]
@@ -34,6 +36,7 @@ graph TD
         HOPPER["src/hopper/<br/>Hopper launch & Unix-socket protocol<br/>BridgeLauncher, HopperClient, protocol"]
         GHIDRA["src/ghidra/<br/>Ghidra discovery, profile & function analysis<br/>snapshot, Unix/Windows transport, bounded lifecycle"]
         IDA["src/ida/<br/>Upstream MCP contract adaptation<br/>live GUI binding or owned headless database"]
+        KUNA["src/kuna/<br/>BYO Kuna deep analysis candidate<br/>discovery reads metadata; version probe on target open"]
         IDA_MCP["External ida-pro-mcp<br/>GUI proxy or database supervisor<br/>upstream installation and engine lifecycle"]
         AUX["src/artifacts/ + src/native/<br/>artifact inventory, bounded directory triage and extraction<br/>format readers and native capabilities"]
         BROWSER["src/browser/<br/>CDP / Playwright capture<br/>captured scripts and native module resolution<br/>execution/: coverage, listener and source attribution"]
@@ -112,6 +115,7 @@ graph TD
     COMPOSITION --> HOPPER
     COMPOSITION --> GHIDRA
     COMPOSITION --> IDA
+    COMPOSITION --> KUNA
     COMPOSITION --> AUX
     IDA --> IDA_MCP
     IDA --> CONTRACTS
@@ -142,6 +146,7 @@ graph TD
     GHIDRA --> GHIDRA_BRIDGE
     HOPPER --> PROCESS
     GHIDRA --> PROCESS
+    KUNA --> PROCESS
     GHIDRA --> PROVIDER_OWNERS
     APP --> PROVIDER_OWNERS
     PROVIDER_OWNERS --> PROCESS
@@ -159,6 +164,7 @@ graph TD
     CONTRACTS --> DOMAIN
     HOPPER --> DOMAIN
     GHIDRA --> DOMAIN
+    KUNA --> DOMAIN
     AUX --> DOMAIN
     BROWSER --> DOMAIN
     PROCESS --> DOMAIN