migtools · anarnold97 · Feb 6, 2026 · Feb 6, 2026
diff --git a/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc b/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc
@@ -4,6 +4,10 @@
 ifdef::context[:parent-context-of-analyzing-applications-mta-cli: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: assess-migration-effort-cli
+// Statement: When I use the CLI, I want to analyze my applications so I can assess and prioritize migration effort.
+// Persona: Developer
+
 
 ifndef::context[]
 [id="analyzing-applications-mta-cli"]
@@ -16,7 +20,7 @@ endif::[]
 :context: analyzing-applications-mta-cli
 
 [role="_abstract"]
-To assess and prioritize migration and modernization efforts for applications written in different languages, analyze your applications by using the {ProductFullName} {CLINameTitle}. 
+Assess and prioritize migration effort by analyzing your Java applications with the {ProductFullName} CLI. Run single- or multiple-app analysis and get reports that highlight required changes.
 
 Depending on your scenario, you can use the {ProductShortName} CLI to perform the following actions:
 
@@ -40,7 +44,7 @@ The analysis output in the disconnected environment usually results in fewer inc
 {ProductShortName} CLI supports running source code and binary analysis by using `analyzer-lsp`. `analyzer-lsp` is a tool that evaluates rules by using language providers.
 
 include::topics/mta-cli/proc_analyzing-single-app-with-mta-cli.adoc[leveloffset=+1]
- 
+
 include::topics/mta-cli/proc_analyzing-multiple-apps-with-mta-cli.adoc[leveloffset=+1]
 
 include::topics/mta-cli/proc_running-the-containerless-mta-cli.adoc[leveloffset=+1]
@@ -49,4 +53,3 @@ include::topics/mta-cli/ref_mta-cli-analyze-flags.adoc[leveloffset=+1]
 
 ifdef::parent-context-of-analyzing-applications-mta-cli[:context: {parent-context-of-analyzing-applications-mta-cli}]
 ifndef::parent-context-of-analyzing-applications-mta-cli[:!context:]
-
diff --git a/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc b/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc
@@ -4,6 +4,10 @@
 ifdef::context[:parent-context-of-analyzing-multi-language-applications: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: assess-migration-effort-cli
+// Statement: When I use the CLI, I want to analyze my applications so I can assess and prioritize migration effort.
+// Persona: Developer
+
 
 ifndef::context[]
 [id="analyzing-nonjava-applications"]
@@ -16,7 +20,7 @@ endif::[]
 :context: analyzing-nonjava-applications
 
 [role="_abstract"]
-To assess the migration effort for applications written in languages other than Java, you can analyze your source code by using the {ProductFullName} command-line interface (CLI). The analysis identifies dependencies and potential migration issues, helping you prioritize tasks and estimate the resources required to modernize your non-Java portfolio.
+Assess migration effort for non-Java applications with the {ProductFullName} CLI. The analysis identifies dependencies and migration issues so you can prioritize and estimate modernization effort.
 
 You can perform the analysis either of the following ways:
 

diff --git a/assemblies/cli-guide/assembly_generating-assets.adoc b/assemblies/cli-guide/assembly_generating-assets.adoc
@@ -4,6 +4,10 @@
 ifdef::context[:parent-context-of-generating-assets: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: generate-deployment-assets
+// Statement: When I am ready to deploy, I want to generate deployment manifests and assets so I can move my application to the target platform.
+// Persona: Developer, DevOps
+
 
 ifndef::context[]
 [id="generating-assets"]
@@ -16,7 +20,7 @@ endif::[]
 :context: generating-assets
 
 [role="_abstract"]
-To enable offline review and simplify the distribution of assessment results, you can generate static assets by using the {ProductFullName} command-line interface. This process produces standalone reports and data files, allowing you to share migration insights with stakeholders without requiring access to the analysis environment.
+Generate static reports and deployment manifests with the {ProductFullName} CLI so you can share migration insights and deploy Cloud Foundry applications to {ocp-short}. Use the `discover` and `generate` commands in containerless mode.
 
 You can use the `discover` and `generate` commands in containerless mode to automatically generate the manifests needed to deploy a Cloud Foundry (CF) application in the {ocp-short}: 
 

diff --git a/assemblies/cli-guide/assembly_performing-transformation.adoc b/assemblies/cli-guide/assembly_performing-transformation.adoc
@@ -4,6 +4,9 @@
 ifdef::context[:parent-context-of-performing-transformation: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: transform-source-code
+// Statement: When I have analysis results, I want to transform my application source code so I can apply automated migration recipes.
+// Persona: Developer
 
 ifndef::context[]
 [id="performing-transformation"]
@@ -13,22 +16,18 @@
 endif::[]
 = Performing a transformation with the {ProductShortName} command-line interface
 
-
 :context: performing-transformation
 
 [role="_abstract"]
-To accelerate your application modernization, use the {ProductFullName} command-line interface (CLI) to transform your source code. The transformation process applies predefined migration rules to your codebase, reducing the manual effort required to update Java libraries or frameworks.
+So you can apply automated migration recipes. Use the {ProductFullName} CLI to transform source code and apply predefined migration rules to reduce manual effort.
 
-IMPORTANT: Performing transformation requires the container runtime to be configured. 
-
+IMPORTANT: Performing transformation requires the container runtime to be configured.
 
 include::topics/mta-cli/proc_transforming-application-source-code.adoc[leveloffset=+1]
 
 include::topics/mta-cli/ref_available-openrewrite-recipes.adoc[leveloffset=+1]
 
 include::topics/mta-cli/ref_openrewrite-command-options.adoc[leveloffset=+1]
 
-
 ifdef::parent-context-of-performing-transformation[:context: {parent-context-of-performing-transformation}]
 ifndef::parent-context-of-performing-transformation[:!context:]
-
diff --git a/assemblies/cli-guide/assembly_reference-material.adoc b/assemblies/cli-guide/assembly_reference-material.adoc
@@ -4,17 +4,12 @@
 ifdef::context[:parent-context-of-reference-material: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: reference-and-resources
+// Statement: When I need details on options, paths, or reference material, I want to find CLI flags, migration paths, and contributing info in one place.
+// Persona: Developer
 
-ifndef::context[]
-[id="reference-material"]
-endif::[]
-ifdef::context[]
-[id="reference-material_{context}"]
-[appendix,id="reference-material"]
-endif::[]
-= Reference material
 
-:context: reference-material
+ifndef::Look up CLI options and migration paths Contribute to MTA
 
 [role="_abstract"]
 View the {ProductFullName} command-line interface (CLI) reference resources that might help you when using the CLI. The resources include information about technology tags and rule story points.

diff --git a/assemblies/cli-guide/assembly_reviewing-analysis-reports.adoc b/assemblies/cli-guide/assembly_reviewing-analysis-reports.adoc
@@ -1,6 +1,10 @@
 :_newdoc-version: 2.18.5
 :_template-generated: 2025-06-16
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: assess-migration-effort-cli
+// Statement: When I use the CLI, I want to analyze my applications so I can assess and prioritize migration effort.
+// Persona: Developer
+
 
 ifdef::context[:parent-context-of-reviewing-analysis-reports: {context}]
 
@@ -15,7 +19,7 @@ endif::[]
 :context: reviewing-analysis-reports
 
 [role="_abstract"]
-To assess application portability and estimate the effort required for modernization, review the analysis reports generated by the {ProductFullName} command-line interface (CLI). These reports provide detailed insights into dependencies and potential migration issues, helping you prioritize tasks and verify your migration path.
+Review {ProductFullName} CLI analysis reports to assess portability and estimate modernization effort. Reports show dependencies and migration issues so you can prioritize tasks and verify your migration path.
 
 include::topics/mta-cli/proc_accessing-analysis-report.adoc[leveloffset=+1]
 

diff --git a/assemblies/developer-lightspeed-guide/assembly_getting-started.adoc b/assemblies/developer-lightspeed-guide/assembly_getting-started.adoc
@@ -4,6 +4,9 @@
 ifdef::context[:parent-context-of-getting-started: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: use-developer-lightspeed
+// Statement: When I want AI-assisted code fixes, I want to use Developer Lightspeed so I can resolve migration issues with LLM suggestions.
+// Persona: Developer
 
 ifndef::context[]
 [id="getting-started"]
@@ -16,10 +19,13 @@ endif::[]
 :context: getting-started
 
 [role="_abstract"]
-The Getting started section contains information to walk you through the prerequisites, persistent volume requirements, installation, and workflows that help you to decide how you want to use {mta-dl-full}.
+Get started with {mta-dl-full}: prerequisites, persistent volume requirements, installation, and workflows to resolve migration issues with LLM suggestions.
 
+include::topics/developer-lightspeed/con_prerequisites.adoc[leveloffset=+1]
 
+include::topics/developer-lightspeed/con_installation.adoc[leveloffset=+1]
+
+include::topics/developer-lightspeed/con_developer-lightspeed-pathways.adoc[leveloffset=+1]
 
 ifdef::parent-context-of-getting-started[:context: {parent-context-of-getting-started}]
 ifndef::parent-context-of-getting-started[:!context:]
-
diff --git a/assemblies/intellij-plugin-guide/assembly_resolving-issues.adoc b/assemblies/intellij-plugin-guide/assembly_resolving-issues.adoc
@@ -4,11 +4,12 @@
 ifdef::context[:parent-context-of-intellij-resolving-issues: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: use-intellij-plugin
+// Statement: When I develop in IntelliJ IDEA, I want to run MTA analysis and apply quick fixes so I can migrate from within the IDE.
+// Persona: Developer
 
-ifndef::context[]
-[id="intellij-resolving-issues"]
-endif::[]
-ifdef::context[]
+
+ifndef::context[]Install IntelliJ plugin and run analysis Review and resolve issuesntext[]
 [id="intellij-resolving-issues_{context}"]
 endif::[]
 :context: intellij-resolving-issues

diff --git a/assemblies/mta-install-title/assembly_installing-mta-cli.adoc b/assemblies/mta-install-title/assembly_installing-mta-cli.adoc
@@ -16,7 +16,7 @@ endif::[]
 :context: installing-mta-cli
 
 [role="_abstract"]
-You can use the {ProductFullName} command-line interface (CLI) to assess and prioritize migration and modernization efforts for applications. You can use different command options to adapt the CLI behavior to your needs. You can tune the {ProductShortName} analysis options or integrate with external automation tools.
+Install the {ProductFullName} CLI on Linux, Windows, or macOS to assess and prioritize migration efforts. Use the CLI with Docker (Developer Preview) or integrate with external automation.
 
 You can install the {ProductShortName} command-line interface (CLI) on Linux, Windows, or macOS operating systems. You can also install the CLI for use with Docker on Windows. Note, however, that this is a Developer Preview feature only.
 

diff --git a/assemblies/mta-install-title/assembly_installing-mta-ui.adoc b/assemblies/mta-install-title/assembly_installing-mta-ui.adoc
@@ -4,18 +4,15 @@
 ifdef::context[:parent-context-of-installing-mta-ui: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: install-and-configure-mta
+// Statement: When I adopt MTA, I want to install and configure the CLI or UI so I can start analyzing and migrating applications.
+// Persona: Admin, Developer
 
-ifndef::context[]
-[id="installing-mta-ui"]
-endif::[]
-ifdef::context[]
-[id="installing-mta-ui_{context}"]
-endif::[]
-= Installing the {ProductName} user interface
-:context: installing-mta-ui
+
+ifndef::coInstall CLI (zip or Docker) Install and configure MTA UI/operator-mta-ui
 
 [role="_abstract"]
-By using the {ProductFullName} user interface (UI), you can assess the risks involved in containerizing an application for hybrid cloud environments on Red Hat OpenShift. You can also analyze the changes that you must apply to the application's code to containerize the application. You can install the {ProductName} UI on all Red Hat OpenShift cloud services and Red Hat OpenShift self-managed editions.			
+Install the {ProductFullName} UI on OpenShift to assess containerization risks and analyze code changes. Use the {ProductShortName} Operator to create and manage instances.
 
 To create {ProductShortName} instances, you must install the {ProductShortName} Operator first. The {ProductShortName} Operator is a structural layer that manages resources deployed on Red Hat OpenShift, such as database, front end, and back end, to automatically create an {ProductShortName} instance. 
 

diff --git a/assemblies/mta-install-title/assembly_intro-to-mta.adoc b/assemblies/mta-install-title/assembly_intro-to-mta.adoc
@@ -15,7 +15,7 @@ endif::[]
 :context: intro-to-mta
 
 [role="_abstract"]
-The {ProductFullName} is a set of tools that you can use to accelerate large-scale application modernization efforts across hybrid cloud environments on Red Hat OpenShift. {ProductShortName} looks for common resources and problematic spots when migrating applications. It gives a high-level view of the technologies used by the application. {ProductShortName} also generates a detailed report that evaluates a migration or modernization path. By using this report, you can estimate the effort needed for large-scale projects and reduce the workload involved in the process. 
+Use {ProductFullName} to accelerate application modernization on Red Hat OpenShift. Assess applications, analyze migration paths, and generate reports to estimate effort and reduce workload.
 
 By using {ProductShortName}, you can perform the following tasks: 		
 

diff --git a/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc b/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc
@@ -15,7 +15,7 @@ endif::[]
 :context: red-hat-build-of-keycloak
 
 [role="_abstract"]
-Starting from version 7.3.0, the {ProductFullName} uses the link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0[Red Hat Build of Keycloak (RHBK)] instance for user authentication and authorization. A RHBK instance is installed during the installation of the {ProductShortName} user interface. The {ProductShortName} Operator manages the RHBK instance and configures a dedicated realm with necessary roles and permissions. 
+{ProductFullName} uses Red Hat Build of Keycloak (RHBK) for user authentication and authorization. The {ProductShortName} Operator installs and manages the RHBK instance and configures a dedicated realm.
 
 You can use the {ProductShortName}-managed RHBK instance to perform advanced RHBK configurations, such as link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/user-storage-federation#adding_a_provider[adding a provider for User Federation] or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/identity_broker[integrating identity providers]. 
 

diff --git a/assemblies/rules-development-guide/assembly_creating-rule.adoc b/assemblies/rules-development-guide/assembly_creating-rule.adoc
@@ -4,14 +4,8 @@
 ifdef::context[:parent-context-of-creating-rule: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
-
-ifndef::context[]
-[id="creating-rule"]
-endif::[]
-ifdef::context[]
-[id="creating-rule_{context}"]
-endif::[]
-= Creating custom rules
+// JTBD job: develop-custom-rules
+// Statement: When MTA does not cover my migration scenario, I want to create custom YAML rules so I can extend analysis and transformation forCreate YAML rules and rulesets Use conditions, actions, and providersustom rules
 
 :context: creating-rule
 

diff --git a/assemblies/rules-development-guide/assembly_rule-rulesets.adoc b/assemblies/rules-development-guide/assembly_rule-rulesets.adoc
@@ -4,18 +4,23 @@
 ifdef::context[:parent-context-of-rule-rulesets: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: develop-custom-rules
+// Statement: When MTA does not cover my migration scenario, I want to create custom YAML rules so I can extend analysis and transformation for my stack.
+// Persona: Advanced developer, Architect
 
 ifndef::context[]
 [id="rule-rulesets"]
 endif::[]
 ifdef::context[]
 [id="rule-rulesets_{context}"]
 endif::[]
-= Rulesets
+= Rule rulesets
 
 :context: rule-rulesets
 
 [role="_abstract"]
+Create YAML rules and rulesets. Use conditions, actions, and providers to group rules that achieve a common goal.
+
 A set of rules forms a ruleset. {ProductShortName} does not require every rule file to belong to a ruleset, but you can use rulesets to group multiple rules that achieve a common goal and to pass the rules to the rules engine.
 
 To use multiple rule files, you can either:

diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc
@@ -4,14 +4,8 @@
 ifdef::context[:parent-context-of-rule-yaml-actions: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
-
-ifndef::context[]
-[id="rule-yaml-actions"]
-endif::[]
-ifdef::context[]
-[id="rule-yaml-actions_{context}"]
-endif::[]
-= Rule actions
+// JTBD job: develop-custom-rules
+// Statement: When MTA does not cover my migration scenario, I want to create custom YAML rules so I can extend analysis and transformation for myCreate YAML rules and rulesets Use conditions, actions, and providersRule actions
 
 :context: rule-yaml-actions
 

diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc
@@ -4,6 +4,9 @@
 ifdef::context[:parent-context-of-rules-prov-cond: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: develop-custom-rules
+// Statement: When MTA does not cover my migration scenario, I want to create custom YAML rules so I can extend analysis and transformation for my stack.
+// Persona: Rule developer
 
 ifndef::context[]
 [id="rules-prov-cond"]
@@ -16,9 +19,7 @@ endif::[]
 :context: rules-prov-cond
 
 [role="_abstract"]
-The providers are the modular components in charge of analyzing a given language. Providers are able to analyze code by leveraging the Language Server Protocol (LSP). Through the LSP, all code analysis is abstracted away from the analysis engine and left to the specific LSP server to run the search query defined in the rule on the source code. 
-
-Additionally, {ProductShortName} provides a built-in provider with abilities such as XML parsing, running regular expressions on files, and so on.
+Use providers and rule conditions to analyze code with the Language Server Protocol (LSP). {ProductShortName} includes built-in and language-specific providers; the when block in a rule defines matching conditions.
 
 Currently, {ProductShortName} supports the following providers:
 

diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc
@@ -4,11 +4,8 @@
 ifdef::context[:parent-context-of-rule-yaml-metadata: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
-
-ifndef::context[]
-[id="rule-yaml-metadata"]
-endif::[]
-ifdef::context[]
+// JTBD job: develop-custom-rules
+// Statement: When MTA does not cover my migration scenario, I want to create custom YAML rules so I can extend analysis and transformation for my staCreate YAML rules and rulesets Use conditions, actions, and providersxt[]
 [id="rule-yaml-metadata_{context}"]
 endif::[]
 = Rule metadata

diff --git a/assemblies/rules-development-guide/assembly_rules-introduction.adoc b/assemblies/rules-development-guide/assembly_rules-introduction.adoc
@@ -4,12 +4,9 @@
 ifdef::context[:parent-context-of-rules-introduction: {context}]
 
 :_mod-docs-content-type: ASSEMBLY
-
-ifndef::context[]
-[id="rules-introduction"]
-endif::[]
-ifdef::context[]
-[id="rules-introduction_{context}"]
+// JTBD job: develop-custom-rules
+// Statement: When MTA does not cover my migration scenario, I want to create custom YAML rules so I can extend analysis and transformation for my stack.
+// PCreate YAML rules and rulesets Use conditions, actions, and providers_{context}"]
 endif::[]
 = Introduction to rules
 

diff --git a/assemblies/ui-guide/assembly_analyzing-applications.adoc b/assemblies/ui-guide/assembly_analyzing-applications.adoc
@@ -1,19 +1,20 @@
 :_newdoc-version: 2.18.5
 :_template-generated: 2025-09-12
 :_mod-docs-content-type: ASSEMBLY
+// JTBD job: assess-migration-effort-ui
+// Statement: When I use the MTA UI, I want to configure and run application analysis so I can see which lines must change for migration.
+// Persona: Developer, Team lead
+
 
 ifdef::context[:parent-context-of-analyzing-applications: {context}]
 
-ifndef::context[]
-[id="analyzing-applications"]
-endif::[]
-ifdef::context[]
-[id="analyzing-applications_{context}"]
-endif::[]
-= Analyzing an application with MTA
+ifnConfigure and run analysis from the UI Review reports and insightszing an application with MTA
 
 :context: analyzing-applications
 
+[role="_abstract"]
+Configure and run application analysis in the {ProductFullName} UI to see which lines must change for migration or modernization.
+
 You can use the {ProductFullName} user interface (UI) to configure and run an application analysis. The analysis determines which specific lines in the application must be modified before the application can be migrated or modernized. 			
 
 include::topics/mta-ui/proc_configuring-and-running-an-application-analysis.adoc[leveloffset=+1]