docs: unify user journey and clarify build and early deployment flow

api/docs/deployment.dox

@@ -159,9 +159,15 @@ to compile the client with optimizations, \p -O2 for gcc or \p /O2 for cl.
 ***************************************************************************
 \page page_deploy How to Run
 
-Once the DynamoRIO distribution contents are unpacked (see \ref
-sec_package), configuration and execution of applications under DynamoRIO
-is handled by a set of libraries and tools.  On Windows, the
+DynamoRIO can be run from a build tree, an install tree created via
+\ref sec_build_install, or a release package (see \ref sec_package).  See
+\ref page_building for build steps.  Once
+one of these layouts is available, configuration and execution of
+applications under DynamoRIO is handled by a set of libraries and tools.
+Helper tools such as \c drrun reside under architecture-specific
+subdirectories like \c bin32/ or \c bin64/ in each layout.  The relative
+subdirectory is consistent, while the absolute path depends on whether
+DynamoRIO is used from a build tree, install tree, or release package.  On Windows, the
 tools are \c drconfig.exe, \c drrun.exe, and \c drinject.exe.  The
 corresponding libraries (whose APIs are exposed by the tools) are \c
 drconfiglib.dll and \c drinjectlib.dll with header files \c dr_config.h and
@@ -173,7 +179,22 @@ When using DynamoRIO as a third-party disassembly library (see \ref
 page_standalone), no deployment is needed, as DynamoRIO does not control a
 target application when used as a regular library.
 
-\section win_deploy Windows Deployment
+\section sec_deploy_launch_models Choosing a Launch Method
+
+\c drrun launches a new process with a one-time configuration in a single step.
+
+\c drconfig writes a persistent configuration for a named application, which
+can be reused across launches.
+
+\c drinject injects into an existing process or launches using an existing
+configuration, enabling two-step workflows.
+
+Before selecting an OS-specific workflow, ensure you have a build tree, an
+install tree, or a release package available.  A first successful run simply
+means launching a target application under DynamoRIO control with the expected
+client or default configuration active.
+
+\section sec_win_deploy Windows Deployment
 
 There are two methods for running a process under DynamoRIO: the one-time
 configure-and-run, and the two-step separate configuration and execution.
@@ -309,7 +330,7 @@ An alternative method to run an application under DynamoRIO is the \ref
 sec_startstop "app_start()/app_stop()" interface, which requires modifying
 application source code.
 
-\section lin_deploy Linux Deployment
+\section sec_lin_deploy Linux Deployment
 
 Once DynamoRIO has been unpacked, the same set of helper binaries as on
 Windows provide flexibility in configuring and executing applications.
@@ -334,8 +355,8 @@ the syscall, additionally pass -skip_syscall.
 % bin64/drrun -attach <target_pid> -c samples/bin64/libbbsize.so
 \endcode
 
-This attach feature requires ptrace capabilities, which can be enabled
-with this command:
+This attach feature requires ptrace capabilities on Linux, which can be
+enabled with this command:
 \code
 % echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
 \endcode
@@ -407,9 +428,11 @@ sec_startstop "app_start()/app_stop()" interface, which requires modifying
 application source code.
 
 
-\section android_deploy Android Deployment
+\section sec_deploy_advanced Advanced / Platform-Specific Deployment
+
+\subsection sec_android_deploy Android Deployment
 
-Android deployment is generally the same as \ref lin_deploy except for the
+Android deployment is generally the same as \ref sec_lin_deploy except for the
 following differences.
 
 For pure native applications, the default configuration file location (if
@@ -453,7 +476,7 @@ everything to work without this step, but we are not able to test on all
 versions or configurations of Android.
 
 
-\section qemu_deploy Running Under QEMU
+\subsection sec_qemu_deploy Running Under QEMU
 
 To run DynamoRIO under QEMU, use the \ref op_xarch_root "-xarch_root"
 option to point at the base directory of the guest system libraries.
@@ -491,7 +514,7 @@ $ sudo systemctl restart systemd-binfmt.service
 ```
 
 
-\section client_ops Passing Options to Clients
+\section sec_client_ops Passing Options to Clients
 
 All of the earlier examples did not need to pass any arguments to the client.
 When using the -c argument to set the client, all arguments between the client
@@ -540,7 +563,7 @@ bin32/drrun -c32 samples/bin32/bbsize.dll -- -c64 samples/bin64/bbsize.dll -- no
 
 The order matters: \c -c32 must come first.
 
-\section multi_client Multiple Clients
+\section sec_multi_client Multiple Clients
 
 DynamoRIO does support multiple clients.  It is each client's
 responsibility, however, to ensure compatibility with other clients.
@@ -563,7 +586,7 @@ opportunity to modify the instruction stream or influence DynamoRIO's
 operation.
 
 
-\section tool_frontend End-User Tools
+\section sec_tool_frontend End-User Tools
 
 A client can be packaged up with DynamoRIO to create an end-user tool.  For
 many tools, a separate front-end executable is not necessary, and \p drrun

api/docs/home.dox

@@ -57,6 +57,21 @@ unmodified applications running on stock operating systems (Windows, Linux,
 or Android, with experimental Mac support) and commodity IA-32, AMD64, ARM,
 and AArch64 hardware.
 
+\section user_journey User Journey
+
+The recommended reading order is an end-to-end flow from obtaining DynamoRIO
+to validating deployment.
+
+- <b>Get and Build DynamoRIO</b>: Obtain the source or release package and
+  produce your first DynamoRIO build by following \ref page_building.
+- <b>Install (Optional)</b>: Create a local install tree and understand build
+  versus install outputs using \ref sec_build_install.
+- <b>Run</b>: Choose how to launch a target under DynamoRIO using
+  \ref sec_deploy_launch_models.
+- <b>Deploy</b>: Follow OS-specific deployment steps in \ref page_deploy.
+- <b>Troubleshoot</b>: Diagnose issues using runtime options and diagnostics in
+  \ref sec_options.
+
 # Existing DynamoRIO-based tools
 
 DynamoRIO is the basis for some well-known external tools:

api/docs/intro.dox

@@ -52,9 +52,13 @@ operating system (Windows, Linux, or Android) and commodity IA-32, AMD64,
 ARM, and AArch64 hardware.  See \ref sec_limit_platforms for details of
 which platform combinations are fully supported.
 
+***************************************************************************
 This document describes the DynamoRIO system and the various APIs that it
-exports for building custom tools.  It is divided into the following
-sections:
+exports for building custom tools.  The DynamoRIO documentation follows an
+end-to-end workflow from obtaining DynamoRIO to validating deployment; for
+the complete build, run, and deploy flow, see the User Journey on the home
+page (\ref user_journey).  This page focuses on client APIs and concepts; it
+is divided into the following sections:
 
 - \subpage page_tutorials
   <br>Gives a few short tutorials on using DynamoRIO and includes slides
@@ -269,7 +273,7 @@ other words, the first registered callback receives event notification
 last.  This scheme gives priority to a callback registered earlier,
 since it can override or modify the actions of clients registered
 later.  Note that DynamoRIO calls each client's dr_client_main() routine
-according to the client's priority (see \ref multi_client and
+according to the client's priority (see \ref sec_multi_client and
 dr_register_client() in the deployment API).
 
 Systems registering multiple callbacks for a single event should be

api/docs/release.dox

@@ -2493,7 +2493,7 @@ I/O and nudges.
     injection is desired, one method of running these binaries
     is to place both libdrpreload.so and libdynamorio's full paths in
     /etc/ld.so.preload.
-    You'll need to use a \ref lin_deploy "separate configure step approach".
+    You'll need to use a \ref sec_lin_deploy "separate configure step approach".
     Don't forget to run drconfig to create a configuration for the
     application first; otherwise, libdrpreload.so will refuse to take
     control.  This method of injection takes control part-way through

api/docs/test_suite.dox

@@ -267,7 +267,7 @@ We also have support for running tests under QEMU emulation.  This is automatica
 $ sudo apt-get install qemu-user qemu-user-binfmt
 ```
 
-For instructions on how to manually run under QEMU, see \ref qemu_deploy.
+For instructions on how to manually run under QEMU, see \ref sec_qemu_deploy.
 
 ## Test Output
 

api/docs/tool.gendox

@@ -43,7 +43,7 @@ bin64/drrun -t drcov -- application arg1 arg2
 \endcode
 
 Those interested in how the -t option works should see
-the section \ref tool_frontend.
+the section \ref sec_tool_frontend.
 
 REPLACE_WITH_GENDOX_SUBPAGES
 - \subpage page_drmemory

clients/drdisas/drdisas.dox

@@ -47,7 +47,7 @@ vpmullq {%k7} %zmm17 0x00000dc0(%ecx)[64byte] -> %zmm16
 
 Cross-architecture decoding in the same binary is not yet supported.
 An AArch64 version can be built to run on x86 following
-[instructions here](@ref sec_aarch_on_x86):
+[instructions here](@ref sec_build_aarch_on_x86):
 \code
 $ uname -m
 x86_64