docs: updates to input schema section (#1002)

update wording
change blockquotes to notes
reformat tables
style changes

Author: TC-MO

sources/platform/actors/development/actor_definition/input_schema/index.md

@@ -1,21 +1,21 @@
 ---
 title: Input schema
 sidebar_position: 2
-description: Learn how to define and easily validate a schema for your Actor's input with code examples. Provide an autogenerated input UI for your Actor's users.
+description: Learn how to define and validate a schema for your Actor's input with code examples. Provide an autogenerated input UI for your Actor's users.
 slug: /actors/development/actor-definition/input-schema
 ---
 
-**Learn how to define and easily validate a schema for your Actor's input with code examples. Provide an autogenerated input UI for your Actor's users.**
+**Learn how to define and validate a schema for your Actor's input with code examples. Provide an autogenerated input UI for your Actor's users.**
 
 ---
 
-Input schema describes the input of an Actor. It's a JSON object consisting of various field types supported by the Apify platform. The Apify platform then generates a user interface for the Actor and also validates the input passed to it when it's been started by the API or by using the Apify Console UI.
+The input schema defines the input parameters for an Actor. It's a `JSON` object comprising various field types supported by the Apify platform. Based on the input schema, the Apify platform automatically generates a user interface for the Actor. It also validates the input data passed to the Actor when it's executed through the API or the Apify Console UI.
 
-This is an example of an **auto-generated UI** for [Website Content Crawler](https://apify.com/apify/website-content-crawler).
+The following is an example of an auto-generated UI for the [Website Content Crawler](https://apify.com/apify/website-content-crawler) Actor.
 
 ![Website Content Crawler input UI](./images/input-ui-website-content-crawler.png)
 
-with an **input schema** defined this way:
+With an input schema defined as follows:
 
 ```json5
 {
@@ -78,4 +78,4 @@ The actual input object passed from the autogenerated input UI to the Actor then
 }
 ```
 
-The following chapters will guide you through the complete [input schema specification](./specification.md), and explain how you can also safely use the input schema to enable users to pass [secrets](./secret_input.md).
+Next, let's take a look at [input schema specification](./specification.md), and the possibility of using input schema to enable users to pass [secrets](./secret_input.md).

sources/platform/actors/development/actor_definition/input_schema/secret_input.md

@@ -4,17 +4,15 @@ description: Learn about making some Actor input fields secret and encrypted. Id
 slug: /actors/development/actor-definition/input-schema/secret-input
 ---
 
-# [](#secret-input)Secret input
-
 **Learn about making some Actor input fields secret and encrypted. Ideal for passing passwords, API tokens, or login cookies to Actors.**
 
 ---
 
-The secret input feature allows you to mark some Actor input fields as secret, causing them to be encrypted when saving an input for an Actor. The input can then be decrypted only inside the Actor.
+The secret input feature lets you mark specific input fields of an Actor as sensitive. When you save the Actor's input configuration, the values of these marked fields get encrypted. The encrypted input data can only be decrypted within the Actor. This provides an extra layer of security for sensitive information like API keys, passwords, or other confidential data.
 
-## Setting an input field as secret
+## How to set a secret input field
 
-To make an input field secret, just add a `"isSecret": true` setting to the input field in the Actor's [input schema](./index.md), like this:
+To make an input field secret, you need to add a `"isSecret": true` setting to the input field in the Actor's [input schema](./index.md), like this:
 
 <!-- eslint-skip -->
 ```json
@@ -36,13 +34,18 @@ To make an input field secret, just add a `"isSecret": true` setting to the inpu
 ```
 
 The editor for this input field will then turn into a secret input, and when you edit the field value, it will be stored encrypted.
+
 <img src={require("./images/secret-input-editor.png").default} alt="Secret input editor" style={{ width: '100%', maxWidth: '822px' }}/>
 
+:::note Type restriction
+
 This is only available for `string` inputs, and the editor type is limited to `textfield` or `textarea`.
 
-## Reading secret input fields
+:::
 
-When you read the Actor input through `Actor.getInput()`, the encrypted fields are automatically decrypted, without any additional code needed (starting with the [`apify` package](https://www.npmjs.com/package/apify) version 3.1.0).
+## Read secret input fields
+
+When you read the Actor input through `Actor.getInput()`, the encrypted fields are automatically decrypted (starting with the [`apify` package](https://www.npmjs.com/package/apify) version 3.1.0).
 
 <!-- eslint-skip -->
 ```js
@@ -66,12 +69,12 @@ If you read the `INPUT` key from the Actor run's default key-value store directl
 
 ## Encryption mechanism
 
-The encryption mechanism used for encrypting the secret input fields is the same dual encryption as in [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#/media/File:PGP_diagram.svg).
+The encryption mechanism used for encrypting the secret input fields is the same dual encryption as in [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#/media/File:PGP_diagram.svg). The secret input field is encrypted using a random key, using the `aes-256-gcm` cipher, and then the key is encrypted using a 2048-bit RSA key.
+
+The RSA key is unique for each combination of user and Actor, ensuring that no Actor can decrypt input intended for runs of another Actor by the same user, and no user can decrypt input runs of the same Actor by a different user. This isolation of decryption keys enhances the security of sensitive input data.
 
-The secret input field is encrypted using a random key, using the `aes-256-gcm` cipher, and then the key is encrypted using a 2048-bit RSA key.
-The RSA key is unique for every user and Actor combination. No Actor can decrypt input meant for runs of another Actor by the same user, and no user can decrypt input runs of the same Actor by a different user.
+During Actor execution, the decryption keys are passed as environment variables, restricting the decryption of secret input fields to occur solely within the context of the Actor run. This approach prevents unauthorized access to sensitive input data outside the Actor's execution environment.
 
-The decryption keys are passed to the Actor runs as environment variables, so the input decryption happens only inside of the Actor run.
 
 ## Example Actor