DOCS-423: Document multi-intermediate PKI chains and create-pki-cert-issuer flag usage

docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md

@@ -26,7 +26,7 @@ The certificate chain includes the following components:
 
 The whole chain of trust can be generated using one dedicated CLI command, which automatically creates:
 
-* **Root** and **Intermediate**PKI Issuers.
+* **Root** and **Intermediate** PKI Issuers.
 
 * **Signer key** with a signed certificate for each issuer which includes the following parameters:
 
@@ -65,7 +65,7 @@ Running the command above will create a **Certificate Chain** under **/My-First-
 
 > ✅ **Tip:**
 >
-> The `pathlen` value can be change by using the `--max-path-len` flag.
+> You can change the `pathlen` value by using the `--max-path-len` flag.
 
 You can find the complete list of parameters for this command in the [CLI Reference - Certificates section.](https://docs.akeyless.io/docs/cli-reference-certificates#chain-of-trust)
 
@@ -112,4 +112,46 @@ Where:
 
 * `csr-file-path`: Path to the CSR that was created earlier.
 
-Running the command above will create a certificate with the called `example.com`, where clicking the **View Certificate Details** button will show the full certificate chain.
+Running the command above will create a certificate with the `example.com` Common Name. Clicking **View Certificate Details** shows the full certificate chain.
+
+## Multi-Intermediate PKI Chains
+
+In some compliance environments you may need a deeper PKI hierarchy, for example:
+
+```text
+Root CA → Intermediate CA 1 → Intermediate CA 2 → Leaf Certificate
+```
+
+`generate-ca` creates a single Root → Intermediate chain in one step. To build a deeper chain, repeat the intermediate layer manually:
+
+1. Run `generate-ca` to create the Root CA and the first Intermediate CA (Intermediate 1).
+2. Create an Intermediate 2 signer key and CSR, then sign that CSR using the Intermediate 1 issuer.
+3. Attach the signed certificate to the Intermediate 2 signer key.
+4. Use `create-pki-cert-issuer` to create a second PKI issuer (Intermediate 2), setting `--signer-key-name` to the Intermediate 2 signer key.
+5. Issue leaf certificates from Intermediate 2.
+
+### Known Limitation: `--allow-subdomains` and Other Flags
+
+`generate-ca` does not expose all PKI issuer configuration options. Flags such as `--allow-subdomains` are not available in `generate-ca` and cannot be applied to the issuers it creates.
+
+> ❗ **Important:**
+>
+> If your intermediate issuer requires `--allow-subdomains` or similar options, you must create it manually using `create-pki-cert-issuer` and pass the flags directly, rather than relying on `generate-ca` to set them automatically.
+
+For example, to create an intermediate issuer that allows subdomains:
+
+```shell
+# Prerequisite: /My-First-Chain/pki/keys/intermediate-2/key already exists
+# and has a certificate signed by /My-First-Chain/pki/issuers/intermediate/issuer.
+
+akeyless create-pki-cert-issuer \
+--name /My-First-Chain/pki/issuers/intermediate-2/issuer \
+--signer-key-name /My-First-Chain/pki/keys/intermediate-2/key \
+--allowed-domains example.com \
+--allow-subdomains \
+--is-ca true \
+--ttl 10d \
+--gw-cluster-url 'https://<Your-Akeyless-GW-URL>:8000'
+```
+
+Refer to the [CLI Reference — Certificates section](https://docs.akeyless.io/docs/cli-reference-certificates) for the full list of `create-pki-cert-issuer` parameters.

docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md

@@ -74,7 +74,6 @@ Where:
 * `name`: A unique name for the DFC Key. The name can include a path to the virtual folder where you want to create a new DFC Key using the slash / separators. If the folder does not exist, it will be created together with the item.
 
 * `alg`: DFC Key type, options: `AES128GCM`, `AES256GCM`, `AES128SIV`, `AES256SIV`, `AES128CBC`, `AES256CBC`, `RSA1024`, `RSA2048`, `RSA3072`, `RSA4096`.
-  .
 
 * `generate-self-signed-certificate`: Whether to generate a self signed certificate with the key. If set, `--certificate-ttl` must be provided.
 
@@ -115,7 +114,7 @@ At this point, we have created the following:
 * **Root CA Key**: A Signer Key with a Self Signed Certificate.
 * **Root PKI Cert Issuer**: To sign new Intermediate CA.
 
-Where **only** certificates with the domain `example.com` will be accepted and valid for 100 days, they will be automatically stored under the `/MyChain/IntermediateCertificates/` folder, with basic constraints of `CA: TRUE` and the mentioned **KeyUsage**, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 30 days before expiration.
+Where **only** certificates with the domain `example.com` will be accepted and valid for 100 days, they will be automatically stored under the `/Chain/Intermediate/Certificates` folder, with basic constraints of `CA: TRUE` and the mentioned **KeyUsage**, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 30 days before expiration.
 
 You can find the complete list of parameters for this command in the [CLI Reference - Certificates](https://docs.akeyless.io/docs/cli-reference-certificates#create-pki-cert-issuer) section.
 
@@ -125,6 +124,14 @@ The next step will be the creation of an **Intermediate Signer Key** with a sign
 
 Intermediate certificates act as a middle-man between the secure root certificates and the server certificates distributed to the public. While a chain will always include at least one intermediate certificate, it may contain multiple ones as well.
 
+### If You Started with `generate-ca`
+
+If you used `generate-ca` as an initial bootstrap, continue this manual flow to add additional intermediate layers.
+
+`generate-ca` creates a single Root → Intermediate chain in one step and does not expose all PKI issuer options. For example, flags such as `--allow-subdomains` must be set manually on `create-pki-cert-issuer`.
+
+For full details, see [Build Your Chain of Trust](https://docs.akeyless.io/docs/build-your-chain-of-trust#multi-intermediate-pki-chains).
+
 ### Create an Intermediate Signer Key
 
 Run the following command to create a **CSR** and a **Key** that will be used as our **Intermediate Signer Key**:
@@ -178,7 +185,7 @@ akeyless create-pki-cert-issuer \
 --locality NY 
 ```
 
-Where **only** certificates with the domain `myexample.com` will be accepted and valid for 30 days, and they will be automatically stored under the `/MyChain/Intermediate/Leaf/` folder, with the **Extended Key Usage** of `client auth`, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 30 days before expiration.
+Where **only** certificates with the domain `myexample.com` will be accepted and valid for 30 days, and they will be automatically stored under the `/MyChain/Intermediate/Leaf/` folder, with the **Extended Key Usage** of `client auth`, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 10 days before expiration.
 
 > ℹ️ **Note:**
 >