Improve readability of instructions

Author: webprofusion-chrisc

docs/hub/guides/ccm.md

@@ -2,47 +2,91 @@
 title: Using with Certify Certificate Manager
 ---
 
-# Summary
-To use Certify Management Hub with existing installations of *Certify Certificate Manager* (CCM) you need to configure each instance to *join* the hub.
+## Summary
 
-- Setup a Joining API key in the hub
-- Configure CCM to join the hub (via UI or command line)
-- Verify that the joining has completed in the hub UI.
+Joining your existing *Certify Certificate Manager* (CCM) instance to a Management Hub allows you to control the instance settings as if you were working in the conventional desktop app, without having to remote into the desktop of each instance.
 
-## Before joining the hub
+To use Certify Management Hub with existing installations you need to:
 
-### Consider Security
-The management hub will have complete control over the Certify Certificate Manager instance settings, including the ability to specify deployment tasks which may include locally executed code (PowerShell etc). 
+1. Set up a Joining API key in the hub
+2. Configure CCM to join the hub (via UI or command line)
+3. Verify that the joining has completed in the hub UI
 
-**Do not join a hub you don't control or trust.**
+## Before Joining the Hub
+
+### Security Considerations
+
+:::warning Important
+
+The management hub will have complete control over the Certify Certificate Manager instance settings, including the ability to specify deployment tasks which may include locally executed code (PowerShell etc).
+
+ **Do not join a hub you don't control or trust.**
+
+ :::
 
 ### Ensure Unique Instance IDs
 
-When CCM is installed and InstanceID value is generated and stored in `C:\ProgramData\certify\appsettings.json` (on Windows).
+When CCM is installed, an InstanceID value is generated and stored in appsettings.json (on Windows).
+
+**Important:** If you have previously used a VM clone to create a new instance of CCM:
+- You must ensure two instances do not share the same Instance ID
+- Duplicate IDs will cause instances to appear as one, and their communication with the hub will conflict
+- One instance may receive edits intended for the other
+
+Instance IDs must be valid (unique) GUID values. If in doubt:
+1. Delete your `appsettings.json` file (or just the instanceID field)
+2. Restart the Certify background service to let the app create a new one
+
+## Setting Up the Hub for Instance Management
+
+### 1. Add a Security Principle for Managed Instances
+
+This step may be unnecessary in current versions where it's auto-created.
 
-If you have previously used a VM clone to create a new instance of *Certify Certificate Manager* you need to ensure two instance do not shared the same Instance ID. Otherwise the instances will appear to be the same one and their communication with the hub will conflict, one instance may receive edits intended for the other instance etc.
+1. In the hub, navigate to **Security > Users**
+2. Click **Add New Security Principle**
+3. Configure as follows:
+   - **Type**: Application/Service
+   - **Title**: "Hub Managed Instance"
+   - **Description**: "Principle for Management Hub Instance Joining"
+4. After adding, click the **Roles icon** (People+ icon) next to the new security principle's ID
+5. Select the `Management Hub Managed Instance` role from Available Roles
+6. Click **Save**
 
- Instance IDs are required to be valid (unique) GUID values, if in doubt, delete your `appsettings.json` (or the instanceID field) and restart the Certify background service to the app create one for you.
+**Note for MSPs:** If you manage instances across different organizations, consider creating multiple joining keys to partition by organization. This allows you to revoke hub access for specific groups without affecting unrelated instances.
 
-## Set up an API key for instances to join the hub
+### 2. Create an API Key for Joining Instances
 
-### Add a security principle to represent managed instances
-If not already present you'll need to start by adding a new security principle to represent managed instances. This is so that an API key can then be created and assigned to that security principle. This is likely to have already have been auto created in current versions of the system.
+1. Navigate to **Settings > Security > API Access**
+2. Click **Add API Token**
+3. Select **Managed Instances Service Principle**
+4. Enter **Instance Joining Key** as the title
+5. Select **Management Hub Managed Instance** as the scoped role
+6. **Important:** Click **Add/Remove Role Scope** to add it to the scope list
+7. Click **Add** to create the new API token
+8. Copy the **Client ID** and **Secret** values - you'll need these for instance configuration
 
-In the hub, under Security > Users, add a new Security Principle, select Application/Service as the principle type, set the Title to "Hub Managed Instance"
+## Joining the Hub
 
-Description as "Principle for Management Hub Instance Joining" or similar, so you know what it's for.
+### Method 1: Using the CCM User Interface
 
-Once added, select the Roles icon (People+ icon) shown next to the ID of the new security principle. Click on the `Management Hub Managed Instance` role from  Available Roles to assign it, then Save.
+1. In *Certify Certificate Manager*, go to **Settings > Management Hub**
+2. Enter the following:
+   - Management Hub API URL
+   - Client ID
+   - Client Secret
+3. Click **Join**
+4. The app will attempt to join the management hub
+5. If successful, the instance will appear in the **Instances** list of the Management Hub UI
 
-If you are managing instances across different organizations (for instance, your are an Managed Service Provider) you may wish to use multiple joining keys to partition by organizations, so that groups of instances can have their hub access removed without affecting other unrelated instances.
+### Method 2: Using the Command Line
 
-### Add an API key for joining instances
+Run the following command:
 
-Go to Settings > Security > API Access, select Add API Token, select *Managed Instances Service Principle*, enter *Instance Joining Key* as the title, select *Management Hub Managed Instance* as the scoped role, important: remember to select Add/Remove Role Scope to add it to the scope list. Then select Add and the new API token will be created. Copy the **Client ID** and **Secret** values as they are required for API access.
+```
+certify hub join <url of mgmt hub API> <client id> <client secret>
+```
 
-## Joining the hub
-In *Certify Certificate Manager*, under Settings > Management Hub, set the Management Hub API URL, Client ID and Client Secret, then select Join. The app will attempt to join the management hub and if successful the instance will appear on the Instances list of the Management Hub UI.
+## Verification
 
-To join the hub from the command line:
-`certify hub join <url of mgmt hub API> <client id> <client secret>`
+After joining, confirm that your instance appears in the Management Hub UI's **Instances** list.