From 0b2a259ecbffc0b9308987f47f7616c8f3a03547 Mon Sep 17 00:00:00 2001
From: Alessandro Digilio <alessandro.digilio@hotmail.it>
Date: Thu, 29 Oct 2026 20:27:26 +0100
Subject: [PATCH 1/2] =?UTF-8?q?docs(readme):=20=F0=9F=93=9D=20add=20certif?=
 =?UTF-8?q?icate=20workflow=20overview?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/README.md b/README.md
index e86b7ee..a066326 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,34 @@ Issue, renew, revoke, package, and share client certificates for mutual TLS.
 The toolkit runs a pinned Smallstep CA with Docker Compose and uses the `step`
 CLI for certificate operations.
 
+## Quick start
+
+Start a local CA, issue a client certificate, and inspect the local inventory:
+
+```bash
+cp .env.example .env
+# Set a strong STEP_CA_PASSWORD in .env
+docker compose up -d
+./issue-client-cert.sh laptop
+./cert-manager.sh inventory
+```
+
+The issue command creates a certificate, private key, PKCS#12 bundle, and ZIP
+under `certs_output/laptop/`. The private key stays out of the ZIP unless you
+explicitly enable `INCLUDE_RAW_KEY_IN_ZIP=true`.
+
+```mermaid
+flowchart LR
+    A[Local Smallstep CA] -->|issue| B[Client identity]
+    B --> C[PEM certificate and key]
+    B --> D[PKCS#12 bundle]
+    D --> E[Optional ZIP for transfer]
+    A --> F[CRL and OCSP status]
+```
+
+This diagram shows the local workflow. Revocation is effective only when the
+service using the certificate checks CRL or OCSP status.
+
 ## Security model
 
 This project manages private keys and passwords. Read these points before using

From dea0e20e72b34ada1bb3f40860397a41ff01d4f5 Mon Sep 17 00:00:00 2001
From: Alessandro Digilio <alessandro.digilio@hotmail.it>
Date: Thu, 29 Oct 2026 20:31:54 +0100
Subject: [PATCH 2/2] =?UTF-8?q?docs(safety):=20=F0=9F=93=9D=20clarify=20CA?=
 =?UTF-8?q?=20readiness=20and=20private-key=20packaging?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index a066326..04c55ef 100644
--- a/README.md
+++ b/README.md
@@ -10,19 +10,29 @@ CLI for certificate operations.
 
 ## Quick start
 
-Start a local CA, issue a client certificate, and inspect the local inventory:
+Install the [requirements](#requirements), then start a local CA:
 
 ```bash
 cp .env.example .env
 # Set a strong STEP_CA_PASSWORD in .env
 docker compose up -d
+docker compose logs --follow step-ca
+```
+
+On the first run, initialization takes time. Wait for the logs to report that
+the CA server is listening, then press Ctrl-C to stop following the logs.
+The container keeps running. Issue a client certificate and inspect the inventory:
+
+```bash
 ./issue-client-cert.sh laptop
 ./cert-manager.sh inventory
 ```
 
 The issue command creates a certificate, private key, PKCS#12 bundle, and ZIP
-under `certs_output/laptop/`. The private key stays out of the ZIP unless you
-explicitly enable `INCLUDE_RAW_KEY_IN_ZIP=true`.
+under `certs_output/laptop/`. The ZIP contains private-key material inside the
+password-protected PKCS#12 bundle. Only the separate raw PEM key file is excluded
+unless you explicitly enable `INCLUDE_RAW_KEY_IN_ZIP=true`. Treat both the ZIP
+and its password as sensitive.
 
 ```mermaid
 flowchart LR
@@ -30,11 +40,13 @@ flowchart LR
     B --> C[PEM certificate and key]
     B --> D[PKCS#12 bundle]
     D --> E[Optional ZIP for transfer]
-    A --> F[CRL and OCSP status]
 ```
 
-This diagram shows the local workflow. Revocation is effective only when the
-service using the certificate checks CRL or OCSP status.
+This diagram shows the local packaging workflow. The default Compose deployment
+does not configure active revocation checking or a CRL endpoint, and open-source
+step-ca does not provide OCSP. Do not assume that revoking a certificate makes
+an already issued certificate unusable at relying services before expiry.
+See [Smallstep's production guidance](https://smallstep.com/docs/step-ca/certificate-authority-server-production/).
 
 ## Security model
 
@@ -49,8 +61,8 @@ it:
 - generated ZIP files contain the encrypted PKCS#12 bundle and public
   certificates. They are not encrypted themselves.
 - the temporary HTTP server is suitable only for a trusted local network.
-- certificate revocation takes effect only when the relying service checks CRL
-  or OCSP status.
+- the default deployment does not distribute active revocation status. Existing
+  certificates can remain usable at relying services until expiry.
 
 ## Requirements