docs: improve readability across rest-api-guide pages

- Fix typos (Aynchronous, Calssic)
- Use VitePress callout containers (tip/warning/danger/info/details)
- Add subheadings and phase groupings to dense sections
- Simplify wide tables and extract recommendations into callouts
- Break long paragraphs into structured bullet points
- Add collapsible sections for error codes and footnotes
- Standardize emphasis patterns across all pages

Author: phaupt

.github/copilot-instructions.md

@@ -8,9 +8,12 @@ Before using the Swisscom Mobile ID web service, some initial provisioning steps
 
 1. **The Mobile ID customer (your company) has an agreement with Swisscom:**
    - **Connectivity** (Internet or LAN-I) between the **AP** and **Mobile ID** has been established.
-     - The AP’s public source IP address (or range) must be whitelisted in the **Swisscom Firewall**.
    - The customer has delivered the **X.509 client certificate** to Swisscom (see [Create X509 Client Certificates](/rest-api-guide/create-client-certs.md)).
 
+::: warning Firewall Whitelisting
+The AP’s public source IP address (or range) must be whitelisted in the **Swisscom Firewall**. Contact Swisscom to request whitelisting.
+:::
+
 2. **The Mobile ID customer receives from Swisscom:**
    - An **AP_ID** (Application Provider Identifier) value.
    - A **DataToBeDisplayed (DTBD) Prefix** value:
@@ -85,8 +88,10 @@ A certificate-based mutual authentication when accessing the Mobile ID web servi
 - The Enhanced Key Usage value of client certificates must include Client Authentication (`1.3.6.1.5.5.7.3.2`).
   - See **[Create X509 Client Certificates](/rest-api-guide/create-client-certs.md)** for examples of creating self-signed certificates.
 
-- All requests to the Mobile ID service must originate only from servers that you control.
-  - Never send requests directly from client-side code such as mobile apps or JavaScript, as this may compromise your credentials.
+::: danger
+All requests to the Mobile ID service must originate only from servers that you control.
+Never send requests directly from client-side code such as mobile apps or JavaScript, as this may compromise your credentials.
+:::
 
 - To validate the chain of trust for the Mobile ID server certificate:
   - Add the SwissSign Gold CA – G2 root certificate to your client TrustStore.

docs/rest-api-guide/app-provider-client-integration.md

@@ -1,16 +1,25 @@
 # Auto Activation
 ## Introduction
-Auto Activation is an optional feature for APs, which can greatly improve the user experience for Mobile ID SIM authentications. It is applicable for SIM authentication only and this Auto Activation feature is not relevant for Mobile ID App authentications.
 
-Usually, a brand new Mobile ID SIM card must be activated just once on the MyMobileID Portal. With this Mobile ID activation process, the user can set their personal Mobile ID PIN (Set & Confirm PIN) and it will create the required signing key on the SIM card. After that, the SIM card is ready to be used for Mobile ID authentications.
+Auto Activation is an optional feature for Application Providers (APs) that can greatly improve the user experience for Mobile ID SIM authentications.
 
-Auto Activation is an optional feature that is disabled by default but can be enabled per Application Provider. If enabled, a Signature Request to a user with an inactive Mobile ID SIM (which means the user did not yet set their personal Mobile ID PIN) will invoke an implicit activation process during the ongoing signature transaction.
+- **Applicable to**: SIM authentication only (not relevant for Mobile ID App authentications).
+- **Default state**: Disabled by default, but can be enabled per Application Provider.
 
-So, the Auto Activation will achieve both a successful Mobile ID activation and a successful authentication (Signature Response) at the same time! From now on, that user will be Mobile ID active.
+### How it works
 
-From AP perspective, the user will just have a successful authentication and there is no difference whether the user was auto-activated (during the authentication transaction) or not.
+Usually, a brand new Mobile ID SIM card must be activated once on the MyMobileID Portal. During this activation, the user sets their personal Mobile ID PIN and a signing key is created on the SIM card.
 
+With Auto Activation enabled, a Signature Request to a user with an **inactive** Mobile ID SIM will invoke an implicit activation process during the ongoing signature transaction. This achieves:
+
+- A successful Mobile ID activation **and**
+- A successful authentication (Signature Response) at the same time
+
+From the AP perspective, the user simply has a successful authentication -- there is no difference whether the user was auto-activated during the transaction or not.
+
+::: tip
 Auto Activation feature can successfully prevent a fault sub-code 404 (this fault code means that the user did not yet activate their Mobile ID SIM card) which can happen when an AP attempts to do a Mobile ID authentication with a user that has an inactive Mobile ID SIM card.
+:::
 
 ## How to implement this feature
 To enable the Auto Activation feature for an Application Provider (AP), the AP must ensure that the user has accepted the Mobile ID specific terms & conditions prior to proceeding with the auto activation steps.
@@ -25,13 +34,13 @@ From a user perspective, the steps displayed on the mobile device look very simi
 
 ![auto-activation-user-perspective](/img/auto-activation-user-perspective.png)
 
-Note that in case of a successful auto activation, the Mobile ID server sends a Text SMS to the user, to remind the user to create a Mobile ID recovery code [<sup id="a24">24</sup>](#24).
-
-**References**
-
-**Footnotes**
+::: info
+In case of a successful auto activation, the Mobile ID server sends a Text SMS to the user, to remind the user to create a Mobile ID recovery code [<sup id="a24">24</sup>](#24).
+:::
 
+::: details References and Footnotes
 24. <span id="24"></span> Each time a user completes the Mobile ID activation process, they will receive a code that enables them to recover Mobile ID and maintain their existing pairings to service providers, if you lose your phone, change SIM cards or switch to an e-SIM card. See https://mobileid.ch/recovery [↩](#a17)
+:::
 
 
 

docs/rest-api-guide/auto-activation.md

@@ -45,19 +45,12 @@ When constructing an MSS Signature request, the following best-practice guidelin
    **Example DTBD:**
    > `Bank ACME: Proceed with the login? (TXN-3D5K)`
 
----
-
-**Footnotes**
-
+::: details Footnotes
 17. <span id="17"></span> Type of the AP_TransID is xsd:NCName, refer to http://www.datypic.com/sc/xsd/t-xsd_NCName.html [↩](#a17)
-
 18. <span id="17"></span> http://www.w3.org/TR/xmlschema-2/#dateTime [↩](#a17)
-
 19. <span id="17"></span> http://en.wikipedia.org/wiki/UTF-8 [↩](#a17)
-
 20. <span id="17"></span> In mobile telephony GSM 03.38 is the standard character set used in short message service. [↩](#a17)
-
----
+:::
 
 ### Signature Response
 
@@ -85,11 +78,10 @@ The key validation aspects are as follows:
 5. **Implement Proper Fault and Status Handling**
    - Handle all status and fault codes using structured exception handling logic to ensure stable, predictable behavior of the client application.
 
----
-
-**Important Note:**
+::: warning Important
 Certificate revocation checks are not recommended.
 Mobile ID user certificates are never revoked individually — the Mobile ID service backend manages account validity and state directly.
+:::
 
 
 ### Signature Concurrency Control
@@ -134,10 +126,13 @@ cn=midcheptod58qe59:pn,serialnumber=midcheptod58qe59,pseudonym=midcheptod58qe59
 
 For highest level of assurance and a truly strong two-factor-authentication process, an AP should store this value at the first signature and then verify every subsequent signature response if that serial number value still matches.
 
+::: warning
 If the value does not match anymore, it means that the user re-activated their account without a valid recovery option. In such case (serial number mismatch) the 2nd factor (knowledge/inherence) is not assured.
+:::
 
 ## Timeout Value
 
+::: info Recommended Timeout Values
 Use the reference values below to set an appropriate transaction timeout:
 
 | MSS Operation | Transaction Timeout | Client Connection Timeout |
@@ -148,6 +143,8 @@ Use the reference values below to set an appropriate transaction timeout:
 | MSS Receipt | - | 90 seconds |
 | MSS Profile Query | - | 10 seconds |
 
+:::
+
 ## Mobile ID FAQ
 
 Please visit [https://mobileid.ch/en/faq](https://mobileid.ch/en/faq) for a list of frequently asked questions about Mobile ID

docs/rest-api-guide/best-practices.md

@@ -2,13 +2,16 @@
 
 Below are examples how to create a self-signed certificate with OpenSSL and Java Keytool.
 
-Remarks:
+::: info Remarks
 - Use any meaningful value for the distinguished name (CN/O/C values).
 - Use SHA-256 as shown below.
 - Validity can be set to 3 or 5 years. However, the validity is never checked by Mobile ID.
 - The examples create a self-signed certificate (easy to make, no cost).
 - The client certificate's Enhanced Key Usage must include Client Authentication (OID 1.3.6.1.5.5.7.3.2).
-- Provide the resulting `mycert.crt` file to Swisscom and keep your private key / keystore files (`*.jks`, `*.p12`, `*.jks`) securely stored.
+:::
+::: warning
+Provide the resulting `mycert.crt` file to Swisscom and keep your private key / keystore files (`*.jks`, `*.p12`, `*.key`) securely stored. Never share your private key.
+:::
 
 ## OpenSSL
 
@@ -57,5 +60,7 @@ $ keytool -genkey -alias <alias-name> -keyalg RSA -keysize 4096 -validity 1825 \
 
 $ keytool -export -alias <alias-name> -keystore mycert.jks -file mycert.crt
 ```
-Tip: If your JDK supports it, add an Extended Key Usage for client auth during key generation (syntax depends on JDK version), e.g. -ext "ExtendedKeyUsage=clientAuth". Otherwise, you can generate a CSR with keytool and self-sign it with OpenSSL using the ext.cnf shown above.
+::: tip
+If your JDK supports it, add an Extended Key Usage for client auth during key generation (syntax depends on JDK version), e.g. `-ext "ExtendedKeyUsage=clientAuth"`. Otherwise, you can generate a CSR with keytool and self-sign it with OpenSSL using the ext.cnf shown above.
+:::
 

docs/rest-api-guide/create-client-certs.md

@@ -1,26 +1,18 @@
 # Health Status Service
 
-The Mobile ID Health Status Service is a microservice where you can retrieve health state details about the MobileID authentication service. The health state is based on real end-to-end authentication tests that are checked every few minutes. It's free of charge!
+The Mobile ID Health Status Service is a microservice for retrieving health state details about the MobileID authentication service.
 
-For more information, please visit https://digital.swisscom.com/products/mobile-id
-
-## Active Probing
-
-Retrieve a detailed health state about the Mobile ID authentication service. The scope of the health status service includes different telecommunications providers, IP+ and LAN-i endpoints and the geofencing service.
-
-The health status service is free of charge!
+- **Based on**: Real end-to-end authentication tests, checked every few minutes
+- **Scope**: Different telecommunications providers, IP+ and LAN-i endpoints, and the geofencing service
+- **Cost**: Free of charge
 
-## Real End-To-End Testing
-
-Our health status is based on real end-to-end Mobile ID tests that are responded by special robotic equipment at different physical locations.
-
-## MobileID Telecommunications Providers
-
-Checks include Mobile ID SIM cards from Swisscom, Sunrise, Salt.
+For more information, please visit https://digital.swisscom.com/products/mobile-id
 
-## MobileID App
+## What is Monitored
 
-Checks include the Mobile ID mobile application.
+- **Telecommunications Providers**: Mobile ID SIM cards from Swisscom, Sunrise, Salt
+- **Mobile ID App**: The Mobile ID mobile application
+- **End-to-end tests**: Real Mobile ID tests responded by special robotic equipment at different physical locations
 
 ## Health Status Levels