Update script/powershell docs, ccm intro

Author: webprofusion-chrisc

docs/deployment/tasks_intro.md

@@ -46,6 +46,7 @@ Built-in deployment task types, each with UI to configure the task parameters et
 | Deploy to RAS (Direct Access, VPN, SSTP VPN etc)| Provides a basic deployment for RAS. You may require your own script for more sophisticated deployments. |
 | Deploy to RDP Gateway Service| Provides a basic deployment for a local RDP Gateway. You may require your own script for more sophisticated deployments. |
 | Deploy to RDP Listener Service| Provides a basic deployment for a local RDP Listener (Terminal Services). |
+| [Run a PowerShelll Script](../script-hooks.md) | Executes a given PowerShell script |
 | Run a Script | Execute an environment specific script (such as as a windows batch file or a linux bash script). |
 | Stop, Start or Restart a Service | Select a local service to restart. Usually used in conjunction with another deployment task to cause the new certificate to be applied. |
 | Set Certificate Key Permissions | Although not usually required, some services may need read permission granted for the certificate private key. This task adds read permission for the nominated account. |
@@ -55,6 +56,8 @@ Built-in deployment task types, each with UI to configure the task parameters et
 
 Execute a custom [PowerShell script](../script-hooks.md).
 
+For execution-mode selection, PowerShell version behavior, and impersonation considerations see [PowerShell Support and Execution Modes](../guides/powershell-support.md).
+
 Some example scripts (e.g. for `Web Management Service`) are provided under `C:\Program Files\CertifyTheWeb\Scripts\Common`. If you use any of these you should copy the script to your own choice of folder outside of Program Files as any app updates will overwrite the files in this Program Files location and any edits you make will be lost.
 
 #### Passing custom arguments

docs/guides/powershell-support.md

@@ -0,0 +1,97 @@
+---
+id: powershell-support
+title: PowerShell Support and Execution Modes
+slug: /powershell-support
+description: How Certify runs PowerShell-based tasks on Windows and Linux, including Automatic, In Process, and System PowerShell modes.
+---
+
+This page describes how PowerShell-based tasks are hosted in *Certify Certificate Manager*, *Certify Management Agent*, and *Certify Management Hub*, including the [*Run a PowerShell Script*](../script-hooks.md) task and most built-in tasks which rely on PowerShell internally.
+
+## Overview
+
+These products can use either system PowerShell, when available, or an in-process hosted PowerShell. By default, tasks run as the current service user.
+
+These PowerShell execution modes are currently supported:
+
+| Mode | What it does | Typical use |
+| --- | --- | --- |
+| Automatic | Uses system PowerShell where available, then falls back to the embedded in-process host when no suitable system host is available. On Windows this typically means Windows PowerShell 5.1. On Linux this typically means the embedded host. | Recommended default for most tasks. |
+| In Process | Runs the embedded PowerShell 7 host inside the current Certify service process. | Use when you want consistent PowerShell 7 behavior without depending on the machine's local PowerShell installation. |
+| System PowerShell | Starts a separate PowerShell process provided by the operating system. | Use when your script depends on system-installed modules or host-specific behavior. |
+
+If you enable *Settings > General > Service Config > Prefer Modern PowerShell* for your chosen instance, the app will prefer PowerShell 7 where available when launching System PowerShell.
+
+## Automatic Mode
+
+*Automatic* mode is used by default for the *Run a PowerShell Script* task and for most built-in tasks which use PowerShell internally.
+
+On Windows, *Automatic* uses the system PowerShell host by default. This typically means Windows PowerShell 5.1.
+
+On platforms where no suitable system PowerShell host is available, *Automatic* falls back to the embedded in-process PowerShell 7 host. This is the normal behavior for Linux-based installs.
+
+## In Process Mode
+
+*In Process* runs the embedded PowerShell 7 runtime inside the current Certify service process.
+
+Use this mode when you want predictable PowerShell 7 behavior regardless of what is installed on the machine, or when you want to avoid relying on a separate system shell.
+
+This is the closest equivalent to the older embedded-host model, except the embedded engine is now PowerShell 7 rather than embedded Windows PowerShell 5.1. PowerShell 5.1 is no longer available as an embedded option because it depends on a much older .NET runtime than the app uses. 
+
+Currently, system PowerShell modules such as CimCmdlets may not be available In-Process and you should use an alternative mode.
+
+## System PowerShell Mode
+
+*System PowerShell* launches an external PowerShell process provided by the operating system.
+
+Use this mode when your script depends on system-installed modules, Windows-only cmdlets, or behavior which differs between Windows PowerShell 5.1 and PowerShell 7.
+
+## Impersonation and Compatibility
+
+The choice of execution mode can significantly affect compatibility when a task runs using specific credentials or user credential impersonation. Impersonation is currently only supported on Windows.
+
+Differences between modes can affect:
+
+* which PowerShell version and module set are available
+* how Windows logon tokens are applied
+* whether child processes inherit the expected identity and environment
+* access to network resources, remote shares, and Windows-integrated authentication
+
+On Windows, the service is installed as Local System by default. That limits the type and extent of user impersonation available. If you need fuller user impersonation, you may need to run the service as a different user. That usually requires a service migration, including re-encryption of stored credentials, so it is best planned during the initial install.
+
+If your deployment depends on impersonation, network access, launching other processes, or Windows-specific modules, validate the exact task under the same background service context and credentials you use in production.
+
+Not every workflow will behave reliably under impersonation. If required, a staged approach is often more dependable: export the certificate or write the required values to a known location, then complete the final deployment step using your own scheduled task, watcher process, or service running in the target environment.
+
+## PowerShell Execution Policies
+
+PowerShell execution policies may be set by your administrator, which can affect script execution on Windows. The app tries to set the policy to `Unrestricted` by default, but that may conflict with higher-level policy settings.
+
+You can set the default script execution policy in `%PROGRAMDATA%\Certify\serviceconfig.json`, then restart the Certify background service:
+
+* `"PowershellExecutionPolicy":"Unrestricted"`
+* `"PowershellExecutionPolicy":"Bypass"`
+* `"PowershellExecutionPolicy":""` to use the default policy set by your administrator
+
+## Recommended Approach
+
+1. Start with *Automatic* unless you already know you need a specific host.
+2. Switch to *System PowerShell* when you require system-installed Windows modules or host-specific behavior.
+3. Switch to *In Process* when you want consistent embedded PowerShell 7 behavior across environments.
+4. If you use impersonation, test with the real background service and target credentials rather than relying on interactive UI testing alone.
+
+## Quick Diagnostics
+
+If you need to confirm which host is being used, add temporary logging like the following to your script:
+
+```PowerShell
+param($result)
+
+Write-Output ("PowerShell version: " + $PSVersionTable.PSVersion)
+Write-Output ("Edition: " + $PSVersionTable.PSEdition)
+Write-Output ("PSHOME: " + $PSHOME)
+Write-Output ("User: " + [System.Environment]::UserName)
+```
+
+This makes it easier to confirm whether the task is running under Windows PowerShell 5.1, PowerShell 7, the system host, or the embedded in-process host.
+
+For script examples and general scripting guidance, see [Scripting](../script-hooks.md).

docs/intro.md

@@ -4,44 +4,46 @@ title: Get Started with Certify Certificate Manager
 description: Install Certify Certificate Manager on Windows, request your first certificate, plan renewals, and find the next guides to read.
 ---
 
-# Get Started with Certify Certificate Manager
+# Certify Certificate Manager
 
-*Certify Certificate Manager* is a Windows application and background service for requesting, deploying, auto-renewing, and monitoring SSL/TLS certificates from [Let's Encrypt and other ACME certificate authorities](guides/certificate-authorities.md).
+*Certify Certificate Manager* is a Windows application and background service that automates the requesting, deployment, and renewal of SSL/TLS certificates from [Let's Encrypt and other ACME certificate authorities](guides/certificate-authorities.md).
 
-## Best Fit
+![Startup UI](/assets/screens/landing_page.png)
 
-- You manage certificates on Windows Server or Windows desktop systems.
-- You want a desktop UI with a background service handling renewals.
-- You need IIS integration, Windows certificate store deployment, or task-based export and automation.
+## Core Capabilities
 
-## Before You Start
+- Manage configurations via the desktop application, while a dedicated Windows background service handles scheduled certificate renewals.
+- Automatically binds certificates to IIS websites, installs certificates directly to the Windows Certificate Store, or runs deployment tasks to export certificates for other local or remote services.
+- Join your [Certify Management Hub](hub) for extended functionality and multi-server administration and monitoring.
 
-- Use a currently supported Windows version with outbound HTTPS access.
-- Install on the server or workstation that needs the certificate, unless you have a specific remote deployment design.
-- Ensure the domains on the certificate are public and can be validated by either [HTTP validation](http-validation.md) or [DNS validation](dns/validation.md).
-- Plan to stay current with updates. Some changes from certificate authorities are operationally significant, and only the latest version is supported.
+## System & Domain Requirements
 
-## Fastest Path to a Working Certificate
+To use Certify Certificate Manager, your environment should meet the following conditions:
+- Use a supported version of Windows ideally with outbound HTTPS access to contact your chosen Certificate Authority (public or custom).
+- Install the software directly on the server hosting the target service, or use SSH/UNC shares etc to with deployment tasks to sync certificates to other destination systems.
+- Ensure your target domains are active and can complete either [HTTP challenge validation](http-validation.md) (requiring port 80/443 access) or [DNS challenge validation](dns/validation.md) (requiring programmatic control or manual modification of your DNS zone).
+- You must keep the software up to date. Certificate Authorities periodically change their services in ways that may become incompatible. 
 
-1. Install the app using the [installation guide](guides/installation.md).
-2. If you use IIS, keep your hostname bindings in place before starting the first request.
-3. Create a new managed certificate and confirm the domains you want to include.
-4. Choose [HTTP validation](http-validation.md) or [DNS validation](dns/validation.md), then use **Test** if you want to verify the setup before ordering.
-5. Review the [request flow and deployment behavior](certificate-process.md), then request the certificate.
-6. Confirm the result in **Preview** and review [renewal behavior](renewals.md) so you know how monitoring and retry logic works.
+## Quick Start: Requesting Your First Certificate
+
+Setting up a managed certificate generally involves these steps:
+
+1. **Install:** Download and run the installer as described in the [installation guide](guides/installation.md).
+2. **Setup Bindings (IIS):** If you are securing IIS websites, configure your hostname bindings in IIS Manager before beginning.
+3. **Add Managed Certificate:** In the Certify UI, click **New Certificate** and specify the domains you want to secure.
+4. **Configure Challenge Validation:** Choose a validation method ([HTTP](http-validation.md) or [DNS](dns/validation.md)) and click **Test** to ensure path or DNS access is functional prior to placing the actual order.
+5. **Preview**: The Preview tab will show you details of the certificate being ordered and the deployment that will happen, including any matching IIS site bindings the cert will target.
+6. **Request Certificate:** Click **Request Certificate** to fetch and apply your certificate. Review the [request and deployment flow](certificate-process.md) to understand how the process executes.
+7. **Automatic Renewal:** Once a certificate is successfully requested, Certify's background service will schedule it for routine renewal checks. Learn how this operates in the [renewal behavior guide](renewals.md).
 
 
-![Startup UI](/assets/screens/landing_page.png)
 
-## What Happens Next
 
-- The background service handles automatic renewals and routine maintenance.
-- You can extend deployments using [deployment tasks](deployment/tasks_intro.md), [scripting](script-hooks.md), or the [CLI](commandline.md).
-- If you need centralized administration or cross-platform management later, review [Certify Management Hub](hub/).
+## Options for Larger Deployments
 
-<div className="diagram">
-![Products](/assets/diagrams/products.png)
-</div>
+- **Unattended Execution:** The Windows background service runs continuously to manage periodic automated renewals even when no users are logged in.
+- **Automation Tasks:** Extend your deployment pipeline with built-in [deployment tasks](deployment/tasks_intro.md), custom [scripting hooks](script-hooks.md), or the [command line interface (CLI)](commandline.md).
+- **Centralized Administration:** For coordinating across multiple servers or platforms, see the [Certify Management Hub](hub/) documentation.
 
 ## Next Docs to Read