Timi16 · Timi16 · May 28, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -273,7 +273,7 @@ Tips:
 
 ## Claiming and Working on Issues
 
-- Check the issue tracker for open issues and labels like `good first issue` or `help wanted`.
+- Check the [issue tracker](https://github.com/Timi16/soroban-debugger/issues) for open issues and labels like [good first issue](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or [help wanted](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
 - Before starting, comment on the issue to say you want to work on it.
 - If an issue is already assigned, coordinate in the thread before beginning work.
 - Keep one issue per PR when possible, and link the PR to the issue.
@@ -349,22 +349,22 @@ When suggesting a feature, please include:
 We welcome contributions in the following areas:
 
 **Current Focus:**
-- CLI improvements
-- Enhanced error messages
-- Storage inspection
-- Budget tracking
+- [CLI improvements](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3ACLI)
+- [Enhanced error messages](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3A%22error+messages%22)
+- [Storage inspection](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3Astorage)
+- [Budget tracking](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3Abudget)
 
 **Upcoming:**
-- Breakpoint management
-- Terminal UI enhancements
-- Call stack visualization
-- Execution replay
+- [Breakpoint management](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3Abreakpoints)
+- [Terminal UI enhancements](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3ATUI)
+- [Call stack visualization](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3A%22call+stack%22)
+- [Execution replay](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3Areplay)
 
 **Future:**
-- WASM instrumentation
-- Source map support
-- Memory profiling
-- Performance analysis
+- [WASM instrumentation](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3Ainstrumentation)
+- [Source map support](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3A%22source+maps%22)
+- [Memory profiling](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3Aprofiling)
+- [Performance analysis](https://github.com/Timi16/soroban-debugger/issues?q=is%3Aopen+is%3Aissue+label%3Aperformance)
 
 If you have ideas outside these areas, feel free to discuss them by opening an issue.
 

diff --git a/Cargo.toml b/Cargo.toml
@@ -159,5 +159,7 @@ path = "src/bin/bench-regression.rs"
 bench = false
 
 [lib]
+crate-type = ["rlib", "cdylib"]
+
 name = "soroban_debugger"
 crate-type = ["rlib", "cdylib"]
diff --git a/build.rs b/build.rs
@@ -38,6 +38,24 @@ mod debugger {
     }
 }
 
+#[allow(dead_code)]
+mod analyzer {
+    pub mod security {
+        pub enum Severity {
+            Low,
+            Medium,
+            High,
+        }
+    }
+    pub mod symbolic {
+        pub enum SymbolicProfile {
+            Fast,
+            Balanced,
+            Deep,
+        }
+    }
+}
+
 #[allow(dead_code)]
 #[path = "src/cli/args.rs"]
 mod args;

diff --git a/check_output.txt b/check_output.txt
@@ -0,0 +1,49 @@
+    Checking soroban-debugger v0.1.0 (/Users/backenddevopsdeveloper/Downloads/DRIPS/viv-soroban-debugger)
+error[E0425]: cannot find type `DoctorArgs` in this scope
+    --> src/cli/commands.rs:2944:21
+     |
+2944 | pub fn doctor(args: DoctorArgs) -> Result<()> {
+     |                     ^^^^^^^^^^ not found in this scope
+     |
+help: consider importing this struct
+     |
+   1 + use crate::cli::args::DoctorArgs;
+     |
+
+warning: unused imports: `BudgetInspector` and `ResourceCheckpoint`
+ --> src/output.rs:8:32
+  |
+8 | use crate::inspector::budget::{BudgetInspector, ResourceCheckpoint};
+  |                                ^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^
+  |
+  = note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default
+
+warning: unused import: `std::collections::HashSet`
+  --> src/server/debug_server.rs:17:5
+   |
+17 | use std::collections::HashSet;
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+warning: unused import: `Ordering`
+  --> src/server/debug_server.rs:22:36
+   |
+22 | use std::sync::atomic::{AtomicU64, Ordering};
+   |                                    ^^^^^^^^
+
+warning: unused import: `StorageQuery`
+  --> src/ui/dashboard.rs:14:51
+   |
+14 | use crate::inspector::storage::{StorageInspector, StorageQuery};
+   |                                                   ^^^^^^^^^^^^
+
+warning: unused variable: `offsets`
+   --> src/debugger/source_map.rs:630:21
+    |
+630 |                 let offsets = if let Some(offsets) = line_to_offsets.get(requested_line) {
+    |                     ^^^^^^^ help: if this is intentional, prefix it with an underscore: `_offsets`
+    |
+    = note: `#[warn(unused_variables)]` (part of `#[warn(unused)]`) on by default
+
+For more information about this error, try `rustc --explain E0425`.
+warning: `soroban-debugger` (lib) generated 5 warnings
+error: could not compile `soroban-debugger` (lib) due to 1 previous error; 5 warnings emitted
diff --git a/docs/debug-cross-contract.md b/docs/debug-cross-contract.md
@@ -176,7 +176,80 @@ Event: "incremented" = 6
 
 ---
 
-## 8. Git Workflow
+## 8. Isolating Cross-Contract Calls with `--mock`
+
+When debugging the caller contract in isolation, you often do not want the callee contract to execute for real — either because it is not deployed locally, its side-effects interfere with the test, or you simply want to focus on the caller's logic. The `--mock` flag lets you intercept any cross-contract call and return a fixed value instead.
+
+### Syntax
+
+```bash
+soroban-debugger <contract.wasm> --function <fn> \
+  --mock "<CONTRACT_ID>.<function>=<return_value>"
+```
+
+The flag is repeatable. Each `--mock` entry specifies:
+
+| Part | Description |
+|---|---|
+| `CONTRACT_ID` | The contract address whose calls you want to intercept. |
+| `function` | The specific function name on that contract to mock. |
+| `return_value` | The value the mock returns to the caller, expressed as a Soroban-compatible literal. |
+
+### Example: mock the callee during caller debugging
+
+```bash
+soroban-debugger examples/contracts/cross-contract/caller_contract.wasm \
+  --function call_increment \
+  --mock "CALLEE_CONTRACT_ID.increment=7"
+```
+
+With this command, any call from `CallerContract` to `CalleeContract::increment` is intercepted and returns `7` immediately — the callee WASM never executes.
+
+### Mocking multiple callees
+
+```bash
+soroban-debugger caller_contract.wasm --function call_increment \
+  --mock "CONTRACT_A.increment=7" \
+  --mock "CONTRACT_B.get_price=100"
+```
+
+### Mock call log
+
+After the session completes, the debugger prints a **Mock Contract Calls** log summarising every cross-contract call observed during execution and whether it was intercepted (`MOCKED`) or passed through to the real contract (`REAL`):
+
+```
+--- Mock Contract Calls ---
+1. MOCKED  CALLEE_CONTRACT_ID increment (args: [5]) -> 7
+2. REAL    OTHER_CONTRACT_ID  other_fn  (args: [])  -> 42
+```
+
+This log helps you verify that mocked call sites were actually reached during the debug session.
+
+### VS Code launch configuration
+
+In `.vscode/launch.json`, pass mocks via the `mock` array:
+
+```json
+{
+  "type": "soroban-debugger",
+  "request": "launch",
+  "mock": [
+    "CALLEE_CONTRACT_ID.increment=7"
+  ]
+}
+```
+
+### When to use `--mock`
+
+* The callee contract binary is not available locally.
+* You want deterministic callee responses to reproduce a specific caller code path.
+* You are writing unit-style debugging sessions focused on a single contract boundary.
+
+For more advanced mock patterns (storage setup, event expectations), see [mock-helpers.md](mock-helpers.md).
+
+---
+
+## 9. Git Workflow
 
 ```bash
 git checkout -b docs/tutorial-cross-contract
@@ -190,7 +263,7 @@ git push origin docs/tutorial-cross-contract
 
 ---
 
-## 9. Next Steps
+## 10. Next Steps
 
 * Try nested cross-contract calls and watch the stack grow.
 * Add more complex callee logic and test how the caller handles it.

diff --git a/docs/faq.md b/docs/faq.md
@@ -69,7 +69,7 @@ soroban-debug inspect --contract my_contract.wasm
 
 ### 7. Breakpoints are not triggering
 **Cause:** You might be setting a breakpoint on a function that is never called, or the function name is slightly different (e.g., due to name mangling).
-**Fix:** Verify the function name using `soroban-debug inspect`. In `interactive` mode, use `list-breaks` to ensure your breakpoints are registered.
+**Fix:** Verify the function name using `soroban-debug inspect`. In `interactive` mode, use `list-breaks` to ensure your breakpoints are registered and to see their hit counts.
 
 ### 8. Can I set a breakpoint on a specific line number?
 **Answer:** Currently, the debugger supports setting breakpoints only at **function boundaries**.

diff --git a/docs/feature-matrix.md b/docs/feature-matrix.md
@@ -154,7 +154,7 @@ This matrix is derived from:
 
 Related CI contract checks:
 - Coverage enforcement in `.github/workflows/ci.yml` validates `cargo llvm-cov --json --summary-only` schema and requires `.data[0].totals.lines.percent` to exist as a numeric field.
-- Missing-field behavior is regression-tested by `bash scripts/check_benchmark_regressions.sh selftest-coverage-missing-field` to keep schema drift failures actionable.
+- Missing-field behavior is regression-tested by `bash scripts/check_benchmark_regressions.sh selftest-coverage-missing-field`; see [Benchmark regression policy](performance-regressions.md#coverage-parser-self-test) for the exact contract that self-test enforces.
 
 When adding a new CLI flag or DAP capability, update this file alongside the
 implementation to keep gaps explicit rather than implicit.
diff --git a/docs/index.md b/docs/index.md
@@ -5,6 +5,7 @@ Welcome to the Soroban Debugger documentation. This index helps you navigate the
 ## 🏁 Getting Started
 - [Getting Started Guide](getting-started.md) — Your first steps with the debugger.
 - [First Debug Session](tutorials/first-debug.md) — A step-by-step walkthrough.
+- [VS Code Extension Setup](tutorials/vscode-extension-setup.md) — Install the extension, write `launch.json`, and set your first breakpoints.
 - [Installation Guide](installation.md) — Detailed installation instructions for all platforms.
 
 ## 🛠️ Core Features
@@ -28,8 +29,10 @@ Welcome to the Soroban Debugger documentation. This index helps you navigate the
 ## 🎓 Tutorials
 - [Debugging Auth Errors](tutorials/debug-auth-errors.md) — Diagnosing `require_auth()` failures.
 - [Scenario Runner Cookbook](tutorials/scenario-runner.md) — Writing automated integration tests.
+- [Plugin Development Tutorial](tutorials/plugin-development.md) — Build, install, and iterate on a plugin end-to-end.
 - [Symbolic Analysis Budgets](tutorials/symbolic-analysis-budgets.md) — Configuring symbolic exploration.
 - [Understanding Budget Trends](tutorials/understanding-budget.md) — Visualizing resource usage.
+- [Remote Debugging in CI](tutorials/ci-remote-debugging.md) — Setting up remote debugging in a CI environment.
 
 ## 🤝 Contributing & Community
 - [Contributing Guide](../CONTRIBUTING.md) — How to help improve the debugger.
@@ -39,5 +42,7 @@ Welcome to the Soroban Debugger documentation. This index helps you navigate the
 
 ## 📄 Reference
 - [CLI Command Index](cli-command-groups.md) — Detailed reference for all CLI subcommands.
+- [Benchmark Regression Policy](performance-regressions.md) — CI baseline comparison and coverage parser self-test behavior.
 - [Trace JSON Schema](trace-schema.md) — Format of exported execution traces.
-- [Plugin API](plugin-api.md) — Documentation for the debugger plugin system.
+- [Plugin API](plugin-api.md) — Reference documentation for the debugger plugin system.
+- [Scenario Cookbook](scenario-cookbook.md) — Reusable TOML patterns and an end-to-end scenario walkthrough.
diff --git a/docs/issues/backlog-100-issues.md b/docs/issues/backlog-100-issues.md
@@ -22,8 +22,20 @@
 
 ---
 
+## Planning Workflow
+
+Use this file as the inventory, then move into the roadmap for execution decisions:
+
+1. Read the relevant section here to understand the raw issue list and context.
+2. Switch to [roadmap-priorities.md](roadmap-priorities.md#section-rollup) for the section rollup, then use the [Priority Table](roadmap-priorities.md#priority-table) and [Wave Plan](roadmap-priorities.md#wave-plan) to decide sequencing.
+3. When editing this backlog, update the corresponding roadmap row in the same commit so the two files stay in sync.
+
+---
+
 ## Section A — README and Landing Docs (Issues 1–12)
 
+Roadmap view: [Section A priorities](roadmap-priorities.md#section-a--readme-and-landing-docs)
+
 - **I-001** `[IA]` README table of contents is missing; readers must scroll through 420 lines to locate sections.
 - **I-002** `[DOC]` README "Troubleshooting" table has only 3 rows; the full list lives in `docs/remote-troubleshooting.md` without a cross-link from the table.
 - **I-003** `[DOC]` README "Storage Filtering" section duplicates the same pattern table twice (lines 200–209) — consolidate.
@@ -41,6 +53,8 @@
 
 ## Section B — Architecture and Design Docs (Issues 13–22)
 
+Roadmap view: [Section B priorities](roadmap-priorities.md#section-b--architecture-and-design-docs)
+
 - **I-013** `[DOC]` `ARCHITECTURE.md` describes `Stepper` as "(Planned)" with no follow-up issue or tracking link; its current implementation status is unknown.
 - **I-014** `[DOC]` `ARCHITECTURE.md` "Extension Points" section lists four items but omits the plugin system, remote server, and batch executor — all of which now exist.
 - **I-015** `[DOC]` No architecture-level doc covers the VS Code extension / DAP adapter; `ARCHITECTURE.md` only covers the Rust CLI.
@@ -56,6 +70,8 @@
 
 ## Section C — Feature Reference Docs (Issues 23–40)
 
+Roadmap view: [Section C priorities](roadmap-priorities.md#section-c--feature-reference-docs)
+
 - **I-023** `[DOC]` `docs/instruction-stepping.md` (11 KB) covers the feature thoroughly but has no link back to the feature matrix — readers don't know which surfaces support it.
 - **I-024** `[DOC]` `docs/remote-debugging.md` covers TLS setup but doesn't show a complete `launch.json` snippet for the VS Code attach flow.
 - **I-025** `[DOC]` `docs/remote-troubleshooting.md` references a "Local and CI Sandbox Failures" section that exists, but the FAQ (question 27) links to it using anchor syntax that doesn't match the actual heading casing.
@@ -79,23 +95,27 @@
 
 ## Section D — Tutorials (Issues 41–52)
 
+Roadmap view: [Section D priorities](roadmap-priorities.md#section-d--tutorials)
+
 - **I-041** `[DOC]` `docs/tutorials/first-debug.md` doesn't reference the `.soroban-debug.toml` config file, which new users would benefit from knowing about early.
 - **I-042** `[DOC]` `docs/tutorials/scenario-runner.md` shows TOML structure but doesn't document all TOML keys (e.g., `timeout`, `expected_events`, `skip`).
 - **I-043** `[DOC]` `docs/tutorials/debug-auth-errors.md` has empty checkbox items that suggest the tutorial is incomplete.
-- **I-044** `[DOC]` `docs/tutorials/symbolic-analysis-budgets.md` doesn't explain how to interpret the exploration report or act on findings.
-- **I-045** `[DOC]` `docs/tutorials/understanding-budget.md` covers CPU/memory budget but doesn't mention the `--budget-trend` flag or history-based regression detection.
+- **I-044** ~`[DOC]` `docs/tutorials/symbolic-analysis-budgets.md` doesn't explain how to interpret the exploration report or act on findings.~
+- **I-045** ~`[DOC]` `docs/tutorials/understanding-budget.md` covers CPU/memory budget but doesn't mention the `--budget-trend` flag or history-based regression detection.~
 - **I-046** `[DOC]` `docs/doc/tutorials/video-token-transfer.md` lives under `docs/doc/tutorials/` rather than `docs/tutorials/` — inconsistent nesting that breaks the docs IA.
 - **I-047** `[IA]` No tutorial covers plugin development end-to-end; `docs/plugin-api.md` is a reference, not a tutorial.
 - **I-048** `[DOC]` No tutorial covers the VS Code extension setup (installing the extension, writing a `launch.json`, setting breakpoints).
 - **I-049** `[DOC]` No tutorial covers using the TUI (`soroban-debug tui`) — the feature is mentioned in the command index but has no guide.
 - **I-050** `[DOC]` No tutorial covers the upgrade-check workflow (building two WASM versions, running the check, interpreting Safe/Caution/Breaking output).
 - **I-051** `[DOC]` No tutorial covers the REPL (`soroban-debug repl`) — how to enter it, issue commands, and exit.
-- **I-052** `[DOC]` No tutorial covers remote debugging in a CI environment (the typical DevOps use case beyond the local SSH-tunnel workaround).
+- **I-052** ~`[DOC]` No tutorial covers remote debugging in a CI environment (the typical DevOps use case beyond the local SSH-tunnel workaround).~
 
 ---
 
 ## Section E — Contributor Workflow (Issues 53–70)
 
+Roadmap view: [Section E priorities](roadmap-priorities.md#section-e--contributor-workflow)
+
 - **I-053** `[CONTRIB]` `CONTRIBUTING.md` says "Check the issue tracker for open issues and labels like `good first issue`" but doesn't link to the actual filtered GitHub URL.
 - **I-054** `[CONTRIB]` `CONTRIBUTING.md` "Areas for Contribution" lists items in free text; it should link to concrete open GitHub issues or project board columns.
 - **I-055** `[CONTRIB]` `CONTRIBUTING.md` describes the PR checklist but does not explain what "CI/test behavior changes" means or give examples of what N/A covers.
@@ -119,6 +139,8 @@
 
 ## Section F — Release Operations (Issues 71–82)
 
+Roadmap view: [Section F priorities](roadmap-priorities.md#section-f--release-operations)
+
 - **I-071** `[RELEASE]` `docs/release-checklist.md` requires `CHANGELOG.md` to be updated but provides no example entry format, no link to `cliff.toml`, and no `git-cliff` invocation command.
 - **I-072** `[RELEASE]` The release checklist sign-off section uses `@____` placeholder syntax; there is no documented process for assigning owners before a release cycle begins.
 - **I-073** `[RELEASE]` The benchmark threshold (10%/20%) is hardcoded in the release checklist but the actual values are also set in CI scripts — the two can drift without detection.
@@ -136,6 +158,8 @@
 
 ## Section G — Repo Health and Meta (Issues 83–93)
 
+Roadmap view: [Section G priorities](roadmap-priorities.md#section-g--repo-health-and-meta)
+
 - **I-083** `[META]` Several implementation-summary files (`BATCH_EXECUTION_SUMMARY.md`, `IMPLEMENTATION_SUMMARY.md`, `PLUGIN_RELOAD_DIFF_IMPLEMENTATION.md`, `FLAMEGRAPH_IMPLEMENTATION.md`) live in the root and appear to be one-off delivery notes rather than living documentation; a policy for these files is needed.
 - **I-084** `[META]` `PR_DESCRIPTION.md` lives in the repo root — it appears to be a leftover from a PR and should be removed or archived.
 - **I-085** `[META]` No `SECURITY.md` file exists; GitHub displays a warning and security researchers have no disclosed contact point.
@@ -152,6 +176,8 @@
 
 ## Section H — DX and Tooling Quality (Issues 94–100)
 
+Roadmap view: [Section H priorities](roadmap-priorities.md#section-h--dx-and-tooling-quality)
+
 - **I-094** `[DX]` `docs/getting-started.md` (3001 bytes) is the natural entry point for new users but is not linked from the README "Quick Start" section.
 - **I-095** `[DX]` The `feature-matrix.md` "Maintaining This Document" section tells editors which source files to check but doesn't describe a process to detect drift (e.g., a CI check that flags undocumented flags).
 - **I-096** `[DX]` Man pages in `man/man1/` are generated but there's no published HTML equivalent — the `cargo doc` output and man pages are the only machine-generated references.