From 9acf609ac97eec81f03f181badfcc361b2e64ae5 Mon Sep 17 00:00:00 2001
From: shankar0123 <skreddy040@gmail.com>
Date: Tue, 5 May 2026 06:18:24 +0000
Subject: [PATCH] docs: convert ASCII flow diagram to Mermaid in
 test-environment.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per operator audit: every diagram in docs/ should be Mermaid except
in the repo-root README.md. The 'Key Generation Flow (Agent-Side)'
section in docs/contributor/test-environment.md was rendered as a
plain code fence with arrow-prose:

  Server creates job (AwaitingCSR) → Agent polls, sees job →
  Agent generates ECDSA P-256 key pair locally → ...

That was the only non-Mermaid diagram-shaped block left in docs/.

Converted to a Mermaid sequenceDiagram with 5 participants
(certctl-server, issuer connector, certctl-agent, local agent FS,
shared volume) covering the full AwaitingCSR → CSR-submit →
Deployment-job → cert-write → Completed lifecycle.

Audit + verification script: cowork/docs-audit-2026-05-05/mermaid-audit.md.
Re-running the detection script post-fix returns zero non-Mermaid
diagram-like blocks across all 76 docs/ markdown files.

Total Mermaid coverage in docs/ now: 14 docs / 40 blocks.
---
 docs/contributor/test-environment.md | 35 +++++++++++++++++++---------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/docs/contributor/test-environment.md b/docs/contributor/test-environment.md
index cb00461..ed19964 100644
--- a/docs/contributor/test-environment.md
+++ b/docs/contributor/test-environment.md
@@ -813,17 +813,30 @@ All containers share a bridge network (`certctl-test`, subnet 10.30.50.0/24) wit
 
 ### Key Generation Flow (Agent-Side)
 
-```
-Server creates job (AwaitingCSR) → Agent polls, sees job →
-Agent generates ECDSA P-256 key pair locally →
-Agent creates CSR (public key + CN + SANs) →
-Agent POSTs CSR to server → Server signs via issuer →
-Server stores cert, creates Deployment job (Pending) →
-Agent polls, sees Deployment job →
-Agent fetches signed cert from server →
-Agent reads local private key from /var/lib/certctl/keys/ →
-Agent writes cert + key + chain to /nginx-certs/ (shared volume) →
-Job marked Completed
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Srv as certctl-server
+    participant Iss as Issuer connector
+    participant Agt as certctl-agent
+    participant FS as /var/lib/certctl/keys/<br/>(local agent FS)
+    participant Vol as /nginx-certs/<br/>(shared volume)
+
+    Srv->>Srv: create Job (AwaitingCSR)
+    Agt->>Srv: poll for jobs
+    Srv-->>Agt: Job(AwaitingCSR)
+    Agt->>FS: generate ECDSA P-256 keypair
+    Agt->>Agt: build CSR (pubkey + CN + SANs)
+    Agt->>Srv: POST CSR
+    Srv->>Iss: sign CSR
+    Iss-->>Srv: signed cert
+    Srv->>Srv: store cert; create Deployment Job (Pending)
+    Agt->>Srv: poll for jobs
+    Srv-->>Agt: Job(Deployment)
+    Agt->>Srv: GET signed cert
+    Agt->>FS: read private key
+    Agt->>Vol: write cert + key + chain
+    Agt->>Srv: mark Job(Completed)
 ```
 
 ### Shared Volume Architecture