docs: address review feedback for audit log showcase

docs/showcase/cli-tools/audit-log-and-security.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-CleverAgents maintains a tamper-evident **audit log** that records every
+CleverAgents maintains a comprehensive **audit log** that records every
 security-relevant operation: plan applies, cancellations, resource
 modifications, configuration changes, session creations, and more. The
 `agents audit` command group gives you full visibility into this log — list
@@ -14,6 +14,10 @@ log to populating it with real events, filtering by plan/project/type/time,
 drilling into individual entries, and pruning stale records with or without
 interactive confirmation.
 
+> **Specification alignment note:** The `agents audit` command group is
+> implemented and available today. An update to the CLI command synopsis in the
+> project specification is being tracked in [Issue #4450](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/4450).
+
 ## Prerequisites
 
 - CleverAgents installed (`pip install cleveragents`)
@@ -310,6 +314,12 @@ Exit code: `0`
 This deleted 5 entries that were older than 30 days, leaving the 2 recent
 entries intact.
 
+> **Retention guarantee:** Pruning is always a deliberate user action. No
+> automated background process removes audit entries — even when you configure
+> a retention window, entries are only deleted when you explicitly run a prune
+> command or configure an external job to do so. Specification wording is being
+> clarified in [Issue #4452](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/4452).
+
 ---
 
 ### Step 13: Prune with Interactive Confirmation
@@ -456,7 +466,8 @@ $ agents audit prune --help
 6. **Default retention is "keep everything."** Setting `--days 0` (or leaving
    `CLEVERAGENTS_AUDIT_RETENTION_DAYS` unset) means the audit log grows
    indefinitely. Set a retention period for production deployments where
-   storage is a concern.
+   storage is a concern, and schedule `agents audit prune` to run explicitly so
+   deletions are observable.
 
 7. **The `--yes` flag is safe for automation.** Use `agents audit prune --days
    90 --yes` in cron jobs or CI pipelines to enforce a rolling retention
@@ -510,6 +521,28 @@ agents audit prune --days 90 --yes
 
 ---
 
+## Access Control & Security Considerations
+
+- **Access control:** In local mode, the current operating-system user can run
+  any `agents audit` command. In server mode, audit visibility and pruning
+  privileges follow the server's authentication and authorization policies.
+  Ensure only administrators can prune global audit history.
+- **PII in audit records:** Audit entries often include user identifiers (email
+  addresses) and, for authentication events, IP addresses. Treat export and
+  retention policies as you would any store of personally identifiable
+  information.
+- **Integrity guarantees:** The audit log is stored in the deployment database
+  (SQLite locally, PostgreSQL in server deployments). It does not yet provide a
+  cryptographic tamper-evidence chain. For compliance workloads that require
+  immutable storage, regularly export audit entries to an external SIEM or
+  append-only log service.
+- **Invalid input handling:** Commands validate parameters and exit with
+  non-zero status for invalid values (for example, unknown event types or
+  timestamps that cannot be parsed). Capture exit codes in automation to detect
+  these validation failures early.
+
+---
+
 *This example was automatically generated and verified by the CleverAgents UAT system.*
 *Feature area: Audit log and security commands | Test cycle: 1*