docs: document what the certificate commands actually do

The management guide promised that status without a nickname reports
aggregate health; it only succeeds when a single certificate is
enrolled and otherwise asks which one to report on. It also did not
mention that an online verification whose revocation check did not
complete is reported as UNKNOWN.

The troubleshooting guide gains the inspection commands, which exist as
of this change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: denisonbarbosa

docs/how-to/certificates/manage.md

@@ -78,7 +78,7 @@ Certificate 'galacticcafe-CA.Machine.a1b2c3d4e5f6':
 
 ## Check certificate status
 
-Use `status` to check the health of one certificate or, without a nickname, the overall health of all enrolled certificates. Use `--format json` when integrating with monitoring tools.
+Use `status` to check the health of one certificate. The nickname can be omitted only when a single certificate is enrolled; with several enrolled, the command lists their nicknames and asks for one. Use `--format json` when integrating with monitoring tools.
 
 ```output
 > sudo adsysctl certificate status galacticcafe-CA.Machine.a1b2c3d4e5f6
@@ -119,6 +119,18 @@ Certificate 'galacticcafe-CA.Machine.a1b2c3d4e5f6': PASS
   revoked: no
 ```
 
+With `--online`, a revocation check that did not complete is reported as `UNKNOWN` rather than `PASS`, and the command exits nonzero: the certificate is not known to be revoked, but it is not known to be valid either.
+
+```output
+> sudo adsysctl certificate verify galacticcafe-CA.Machine.a1b2c3d4e5f6 --online
+Certificate 'galacticcafe-CA.Machine.a1b2c3d4e5f6': UNKNOWN
+  chain: yes
+  validity: yes
+  key matches certificate: yes
+  revoked: unknown
+  - could not fetch CRL from http://ca01.galacticcafe.com/crl/galacticcafe-CA.crl: connection refused
+```
+
 ## Renew a certificate
 
 Use `renew` to force re-enrollment immediately, bypassing the normal renewal window (30 days before expiry, bounded to a third of the certificate lifetime). Renewal generates a fresh private key, so this is also a rekey operation. Use `--all` to renew every enrolled certificate.

docs/how-to/certificates/troubleshoot.md

@@ -32,6 +32,16 @@ With the native LDAP method, certificates enrolled by ADSys are machine-scoped a
 
 The enrollment state at `/var/lib/adsys/certs/state_$(hostname).<object-id>.json` records the CA, template and file paths of every enrolled certificate, and `openssl x509 -noout -text -in <certificate>` inspects the certificate itself.
 
+`adsysctl certificate` reports the same information without reading those files by hand; see {ref}`howto::certificates-manage`. `list`, `status` and `verify` diagnose an enrollment, and `verify --online` additionally attempts a CRL revocation check:
+
+```output
+> sudo adsysctl certificate verify galacticcafe-CA.Machine.a1b2c3d4e5f6
+Certificate 'galacticcafe-CA.Machine.a1b2c3d4e5f6': PASS
+  chain: yes
+  validity: yes
+  key matches certificate: yes
+```
+
 With the legacy CEPCES method, certificates are managed by `certmonger`. While not encouraged, they can be manipulated with the same tool. This could be helpful for debugging purposes.
 
 ```output