Address Shaina's feedback

Author: kilfoyle

explore-analyze/alerts-cases/watcher/how-watcher-works.md

@@ -184,7 +184,7 @@ Deactivating a watch also enables you to keep it around for future use without d
 
 You can use scripts and templates when defining a watch. Scripts and templates can reference elements in the watch execution context, including the watch payload. The execution context defines variables you can use in a script and parameter placeholders in a template.
 
-{{watcher}} uses the Elasticsearch script infrastructure, which supports [inline](#inline-templates-scripts) and [stored](#stored-templates-scripts). Scripts and templates are compiled and cached by Elasticsearch to optimize recurring execution. Autoloading is also supported. For more information, see [Scripting](../../scripting.md) and [*How to write scripts*](../../scripting/modules-scripting-using.md).
+{{watcher}} uses the Elasticsearch script infrastructure, which supports [inline](#inline-templates-scripts) and [stored](#stored-templates-scripts). Scripts and templates are compiled and cached by Elasticsearch to optimize recurring execution. Autoloading is also supported. For more information, see [Scripting](../../scripting.md) and [*How to write Painless scripts*](../../scripting/modules-scripting-using.md).
 
 
 ### Watch execution context [watch-execution-context]

explore-analyze/images/elasticsearch-painless-where-to-write.png

@@ -12,9 +12,7 @@ products:
 
 You can write a script to do almost anything, and sometimes, that’s the challenge. It’s difficult to know what’s possible with scripts, so these tutorials address common use cases where scripts are particularly helpful.
 
-Painless scripting becomes powerful when applied to real-world scenarios. These tutorials walk you through essential patterns and operations, providing working examples you can modify for your specific use cases. 
-
-# Available tutorials
+Painless scripting becomes powerful when applied to real-world scenarios. These tutorials walk you through essential patterns and operations, providing working examples you can modify for your specific use cases.
 
 * [Accessing document fields and special variables](/explore-analyze/scripting/modules-scripting-fields.md)
 * [Accessing fields in a document](/explore-analyze/scripting/script-fields-api.md)

explore-analyze/scripting/common-script-uses.md

@@ -1,4 +1,5 @@
 ---
+navigation_title: Painless
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting-painless.html
 applies_to:
@@ -11,10 +12,10 @@ products:
 # Introduction to Painless [modules-scripting-painless]
 
 :::{tip}
-This introduction is designed for users new to Painless scripting. If you're already familiar with Painless, refer to the [Painless Language Specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md) for syntax details and advanced features.
+This introduction is designed for users new to Painless scripting. If you're already familiar with Painless, refer to the [Painless language specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md) for syntax details and advanced features.
 :::
 
-Painless is a secure, performant, and flexible scripting language designed specifically for {{es}}. As the default scripting language for {{es}}, Painless lets you safely customize search behavior, data processing, and operations workflows across your Elastic Stack deployments.
+Painless is a secure, performant, and flexible scripting language designed specifically for {{es}}. As the default scripting language for {{es}}, Painless lets you safely customize search behavior, data processing, and operations workflows across your {[stack]} deployments.
 
 ## What is Painless?
 
@@ -24,7 +25,7 @@ Unlike general scripting languages, Painless is purpose-built for {{es}}, enabli
 
 Common use cases include creating new fields based on existing data, calculating time differences between dates, extracting structured data from log messages, and implementing custom business logic in search scoring. For more examples, refer to our step-by-step [tutorials](/explore-analyze/scripting/common-script-uses.md). 
 
-## What are the benefits of Painless?
+## Benefits
 
 Painless enables scripting in various contexts throughout {{es}}, such as:
 
@@ -45,7 +46,7 @@ Painless enables scripting in various contexts throughout {{es}}, such as:
 * Monitor data patterns and trigger alerts with Watcher solutions  
 * Transform alert payloads for targeted notifications and actions
 
-## How does it work?
+## How it works
 
 You can write Painless scripts inline for quick operations or create reusable functions for your data operation. Here’s a sample Painless script applied to data transformation:
 
@@ -57,7 +58,7 @@ String productTitle(String manufacturer, String productName) {
 return productTitle("Elitelligence", "Winter jacket");
 ```
 
-This script demonstrates how Painless works with:
+This script demonstrates a few facets of Painless scripting:
 
 * **Function definition:** Custom `productTitle` function with typed parameters  
 * **Data types:** String and integer parameter handling  
@@ -71,44 +72,17 @@ Painless provides three core benefits across all scripting contexts:
 
 ## Where to write in Painless
 
-:::{image} /explore-analyze/images/elasticsearch-painless-where-to-write.png
-:alt: A graphic showing six different options of where to write Painless scripts
-:::
-
 You can use Painless in multiple contexts throughout {{es}}:
 
-* [**DevTools Console**](/explore-analyze/query-filter/tools/console.md)**:** for interactive script development and testing  
-* [**Ingest Pipelines**](/manage-data/ingest/transform-enrich/ingest-pipelines.md)**:** for data transformation during indexing  
+* [**Dev Tools Console**](/explore-analyze/query-filter/tools/console.md)**:** for interactive script development and testing  
+* [**Ingest pipelines**](/manage-data/ingest/transform-enrich/ingest-pipelines.md)**:** for data transformation during indexing  
 * [**Search queries**](/solutions/search.md)**:** for custom scoring and script fields  
-* [**Runtime Fields**](/manage-data/data-store/mapping/runtime-fields.md)**:** for dynamic field creation  
+* [**Runtime fields**](/manage-data/data-store/mapping/runtime-fields.md)**:** for dynamic field creation  
 * [**Update API:**](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update) for document modification  
 * [**Watcher**](/explore-analyze/alerts-cases/watcher.md)**:** for alert conditions and actions
 
 ## Start scripting
 
-Write your first Painless script by trying out our How to write scripts or jump into Common script use cases for real-world examples using sample data.
-
-For complete syntax and language features, refer to the [Painless Language Specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md).
-
-
-<!--
-
-# Painless scripting language [modules-scripting-painless]
-
-*Painless* is a performant, secure scripting language designed specifically for {{es}}. You can use Painless to safely write inline and stored scripts anywhere scripts are supported in {{es}}.
-
-$$$painless-features$$$
-Painless provides numerous capabilities that center around the following core principles:
-
-* **Safety**: Ensuring the security of your cluster is of utmost importance. To that end, Painless uses a fine-grained allowlist with a granularity down to the members of a class. Anything that is not part of the allowlist results in a compilation error. See the [Painless API Reference](https://www.elastic.co/guide/en/elasticsearch/painless/current/painless-api-reference.html) for a complete list of available classes, methods, and fields per script context.
-* **Performance**: Painless compiles directly into JVM bytecode to take advantage of all possible optimizations that the JVM provides. Also, Painless typically avoids features that require additional slower checks at runtime.
-* **Simplicity**: Painless implements a syntax with a natural familiarity to anyone with some basic coding experience. Painless uses a subset of Java syntax with some additional improvements to enhance readability and remove boilerplate.
-
-
-## Start scripting [_start_scripting]
-
-Ready to start scripting with Painless? Learn how to [write your first script](modules-scripting-using.md).
-
-If you’re already familiar with Painless, see the [Painless Language Specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md) for a detailed description of the Painless syntax and language features.
+Write your first Painless script by trying out our [guide](/explore-analyze/scripting/modules-scripting-using.md) or jump into one of our [tutorials](/explore-analyze/scripting/common-script-uses.md) for real-world examples using sample data.
 
--->
+For complete syntax and language features, refer to the [Painless language specification](elasticsearch://reference/scripting-languages/painless/painless-language-specification.md).

explore-analyze/scripting/modules-scripting-painless.md

@@ -12,8 +12,6 @@ products:
 
 As part of its core design, Painless provides secure scripting capabilities across {{es}}.
 
-## Why Painless is Safe
-
 Introduced in [{{es}} 5.0](https://www.elastic.co/blog/painless-a-new-scripting-language) as a replacement for Groovy, Painless is purpose-built for {{es}}, enabling native performance while preventing unauthorized access to system resources.
 
 By operating in a controlled sandbox environment, Painless ensures that you won’t get compromised when using it. Painless only allows pre-approved operations through fine-grained allowlists. Scripts cannot access file systems, networks, or other system resources that could compromise your cluster while still providing the flexibility you need for search scoring, data processing, and operational automation.
@@ -27,17 +25,17 @@ By operating in a controlled sandbox environment, Painless ensures that you won
 
 The fine-grained allowlist operates as the **first security layer**. Anything that is not part of the allowlist will result in a compilation error.   
 
-The **second layer of security** is [Java Security Manager(JSM)](https://www.oracle.com/java/technologies/javase/seccodeguide.html). As part of its startup sequence, {{es}} enables JSM to limit the actions that portions of the code can take. Painless uses this additional layer of defense to prevent scripts from doing things such as writing files and listening to sockets.
+The **second layer of security** is [Java Security Manager (JSM)](https://www.oracle.com/java/technologies/javase/seccodeguide.html). As part of its startup sequence, {{es}} enables JSM to limit the actions that portions of the code can take. Painless uses this additional layer of defense to prevent scripts from doing things such as writing files and listening to sockets.
 
 {{es}} uses [Seccomp](https://en.wikipedia.org/wiki/Seccomp) in Linux, [Seatbelt](https://www.chromium.org/developers/design-documents/sandbox/osx-sandboxing-design) in macOS, and [ActiveProcessLimit](https://msdn.microsoft.com/en-us/library/windows/desktop/ms684147) on Windows as **additional security layers** to prevent {{es}} from forking or running other processes.
 
 Finally, scripts used in [scripted metrics aggregations](elasticsearch://reference/aggregations/search-aggregations-metrics-scripted-metric-aggregation.md) can be restricted to a defined list of scripts or forbidden altogether. This can prevent users from running particularly slow or resource-intensive aggregation queries.
 
-You can modify the ***allowed script types setting*** to restrict the type of scripts that are allowed to run and control the available [contexts](elasticsearch://reference/scripting-languages/painless/painless-contexts.md) that scripts can run in. To implement additional layers in your defense-in-depth strategy, follow the [{{es}} security principles](/deploy-manage/security.md). 
+You can modify the allowed script types setting to restrict the type of scripts that are allowed to run and control the available [contexts](elasticsearch://reference/scripting-languages/painless/painless-contexts.md) that scripts can run in. As well, you can use the {{es}} [security features](/deploy-manage/security.md) to enhance your defence strategy.
 
 ## Allowed script types setting [allowed-script-types-setting]
 
-{{es}} supports two script types: `inline` and `stored`. By default, {{es}} is configured to run both types of scripts. To limit what type of scripts are run, set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from running, set `script.allowed_types` to `none`. If you use Kibana, set \`script.allowed\_types\` to both or just \`inline\`. Some Kibana features rely on inline scripts and do not function as expected if {{es}} does not allow inline scripts. 
+{{es}} supports two script types: `inline` and `stored`. By default, {{es}} is configured to run both types of scripts. To limit what type of scripts are run, set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from running, set `script.allowed_types` to `none`. If you use Kibana, set `script.allowed_types` to both or just `inline`. Some Kibana features rely on inline scripts and do not function as expected if {{es}} does not allow inline scripts. 
 
 For example, to run `inline` scripts but not `stored` scripts:
 

explore-analyze/scripting/modules-scripting-security.md

@@ -8,7 +8,7 @@ products:
   - id: elasticsearch
 ---
 
-# How to write scripts [modules-scripting-using]
+# How to write Painless scripts [modules-scripting-using]
 
 :::{tip}   
 This guide provides a beginner-friendly introduction to Painless scripting with step-by-step tutorials and practical examples. If you're new to scripting or Painless, this is the recommended starting point.

explore-analyze/scripting/modules-scripting-using.md

@@ -14,35 +14,41 @@ A Painless script is structured as one or more statements and optionally has one
 
 The [Painless execute API](elasticsearch://reference/scripting-languages/painless/painless-api-examples.md) provides the ability to test a script with simple user-defined parameters and receive a result. Let’s start with a complete script and review its constituent parts.
 
-First, index a document with a single field so that we have some data to work with:
-
-```console
-PUT my-index-000001/_doc/1
-{
-  "my_field": 5
-}
-```
-
-We can then construct a script that operates on that field and run evaluate the script as part of a query. The following query uses the [`script_fields`](elasticsearch://reference/elasticsearch/rest-apis/retrieve-selected-fields.md#script-fields) parameter of the search API to retrieve a script valuation. There’s a lot happening here, but we’ll break it down the components to understand them individually. For now, you only need to understand that this script takes `my_field` and operates on it.
-
-```console
-GET my-index-000001/_search
-{
-  "script_fields": {
-    "my_doubled_field": {
-      "script": { <1>
-        "source": "doc['my_field'].value * params['multiplier']", <2>
-        "params": {
-          "multiplier": 2
+1. Index a document
+
+    Index a document with a single field so that we have some data to work with:
+
+    ```console
+    PUT my-index-000001/_doc/1
+    {
+      "my_field": 5
+    }
+    ```
+
+1. Operate on a field
+
+    You can now construct a script that operates on that field and then evaluate the script as part of a query. The following query uses the [`script_fields`](elasticsearch://reference/elasticsearch/rest-apis/retrieve-selected-fields.md#script-fields) parameter of the search API to retrieve a script valuation.
+
+    The components of this script are detailed in later pages. For now, note that the script takes `my_field` as input and operates on it.
+
+    ```console
+    GET my-index-000001/_search
+    {
+      "script_fields": {
+        "my_doubled_field": {
+          "script": { <1>
+            "source": "doc['my_field'].value * params['multiplier']", <2>
+            "params": {
+              "multiplier": 2
+            }
+          }
         }
       }
     }
-  }
-}
-```
+    ```
 
-1. `script` object
-2. `script` source
+    1. `script` object
+    2. `script` source
 
 
-The `script` is a standard JSON object that defines scripts under most APIs in {{es}}. This object requires `source` to define the script itself. The script doesn’t specify a language, so it defaults to Painless.
+    The `script` is a standard JSON object that defines scripts under most APIs in {{es}}. This object requires `source` to define the script itself. Since `script` isn't set, the [scripting language](/explore-analyze/scripting.md) is interpreted as being Painless, by default.

explore-analyze/scripting/modules-scripting-write-first-script.md

@@ -17,7 +17,7 @@ If you're new to Painless contexts, refer to [Painless contexts](elasticsearch:/
 
 ## Technical differences
 
-* [**`doc` values**](#when-to-use-doc-values)) use columnar field value store enabled by default on all the fields except analyzed text fields. They can only return simple field values such as numbers, dates, geo-points, and terms.  
+* [**`doc` values**](#when-to-use-doc-values) are a columnar field value store, enabled by default on all the fields except analyzed text fields. They can only return simple field values such as numbers, dates, geo-points, and terms.
 * [**`ctx` access**](#when-to-use-ctx) provides structured access to document content during modification contexts, with fields accessible as map and list structures for existing document fields.  
 * [**`_source` access**](#when-to-use-source) loads the complete document as a map-of-maps, optimized for returning several fields per result but slower than doc values for single field access.
 
@@ -132,7 +132,7 @@ POST /kibana_sample_data_ecommerce/_update_by_query
 
 ## Next steps
 
-* **New users:** Explore Accessing [Accessing document fields and special variables](/explore-analyze/scripting/modules-scripting-fields.md)  
+* **New users:** Explore [Accessing document fields and special variables](/explore-analyze/scripting/modules-scripting-fields.md)  
 * **Advanced users:** Review [Painless contexts](elasticsearch://reference/scripting-languages/painless/painless-contexts.md) for context-specific implementation details