refactor(cli): dx improvements

.auths/allowed_signers

@@ -1,5 +1,4 @@
 # auths:managed — do not edit manually
-# Current identity (E6IXlw5-lnX88r3WZCt3u1qyN_Xlq7nQjtoTmuOfMIjI)
-z6MktnihicwetvA16FtHFynaJTn9eDZw51eizUEA1yGJCR4o@auths.local namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINT/yz5N7+GkzsRTHiyaueZbDy+fovwYUXyJ9uwD67tk
-# Previous identity
-z6MkipUqayiDZWM8j4YktjiEFZcCGw51YDVvLM7SrYPqLLyZ@auths.local namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEDeaOmUEcUjzChUedAsPyDO4mnjIa8j92fD9rGpuZd0
+# auths:attestation
+z6MkhPJCPXd5A9VN4wScJkxTtz6de7egZQx78vsiAT1vg3PZ@auths.local namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICuPK6OfYp7ngZp40Q+Dsrahhks472v6gPIMD0upCRnM
+# auths:manual

.gitignore

@@ -135,3 +135,4 @@ my-artifact.txt.auths.json
 
 # Stale E2E test artifacts (nested git repos created by test runs)
 tests/e2e/.auths-ci/
+.capsec-cache

crates/auths-cli/src/adapters/system_diagnostic.rs

@@ -1,7 +1,7 @@
 //! POSIX-based diagnostic adapter — subprocess calls live here, nowhere else.
 
 use auths_sdk::ports::diagnostics::{
-    CheckResult, CryptoDiagnosticProvider, DiagnosticError, GitDiagnosticProvider,
+    CheckCategory, CheckResult, CryptoDiagnosticProvider, DiagnosticError, GitDiagnosticProvider,
 };
 use std::process::Command;
 
@@ -23,6 +23,7 @@ impl GitDiagnosticProvider for PosixDiagnosticAdapter {
             passed,
             message,
             config_issues: vec![],
+            category: CheckCategory::Advisory,
         })
     }
 
@@ -57,6 +58,7 @@ impl CryptoDiagnosticProvider for PosixDiagnosticAdapter {
             passed,
             message,
             config_issues: vec![],
+            category: CheckCategory::Advisory,
         })
     }
 }

crates/auths-cli/src/cli.rs

@@ -101,42 +101,29 @@ pub enum RootCommand {
     Signers(SignersCommand),
     Pair(PairCommand),
     Error(ErrorLookupCommand),
-    #[command(hide = true)]
     Completions(CompletionsCommand),
     #[command(hide = true)]
     Emergency(EmergencyCommand),
 
-    #[command(hide = true)]
     Id(IdCommand),
-    #[command(hide = true)]
     Device(DeviceCommand),
-    #[command(hide = true)]
     Key(KeyCommand),
-    #[command(hide = true)]
     Approval(ApprovalCommand),
-    #[command(hide = true)]
     Artifact(ArtifactCommand),
-    #[command(hide = true)]
     Policy(PolicyCommand),
-    #[command(hide = true)]
     Git(GitCommand),
-    #[command(hide = true)]
     Trust(TrustCommand),
-    #[command(hide = true)]
     Namespace(NamespaceCommand),
-    #[command(hide = true)]
     Org(OrgCommand),
-    #[command(hide = true)]
     Audit(AuditCommand),
+    Config(ConfigCommand),
+
     #[command(hide = true)]
     Agent(AgentCommand),
     #[command(hide = true)]
     Witness(WitnessCommand),
     #[command(hide = true)]
     Scim(ScimCommand),
-    #[command(hide = true)]
-    Config(ConfigCommand),
-
     #[command(hide = true)]
     Commit(CommitCmd),
     #[command(hide = true)]

crates/auths-cli/src/commands/approval.rs

@@ -11,7 +11,20 @@ use crate::config::CliConfig;
 pub const EXIT_APPROVAL_REQUIRED: i32 = 75;
 
 #[derive(Parser, Debug)]
-#[command(about = "Manage approval gates")]
+#[command(
+    about = "Manage approval gates",
+    after_help = "Examples:
+  auths approval list       # Show pending approval requests
+  auths approval grant --request <hash> --note 'Reviewed and approved'
+                            # Grant approval for a request
+
+Exit Codes:
+  75 — Approval required (TEMPFAIL) — operation needs authorization
+
+Related:
+  auths policy  — Manage capability policies
+  auths status  — Check system status"
+)]
 pub struct ApprovalCommand {
     #[command(subcommand)]
     pub command: ApprovalSubcommand,

crates/auths-cli/src/commands/artifact/mod.rs

@@ -13,7 +13,26 @@ use auths_core::config::EnvironmentConfig;
 use auths_core::signing::PassphraseProvider;
 
 #[derive(Args, Debug, Clone)]
-#[command(about = "Sign and verify arbitrary artifacts (tarballs, binaries, etc.).")]
+#[command(
+    about = "Sign and verify arbitrary artifacts (tarballs, binaries, etc.).",
+    after_help = "Examples:
+  auths artifact sign package.tar.gz     # Sign an artifact
+  auths artifact sign package.tar.gz --expires-in 2592000
+                                         # Sign with 30-day expiry
+  auths artifact verify package.tar.gz.auths.json
+                                         # Verify artifact signature
+  auths artifact publish package.tar.gz --package npm:react@18.3.0
+                                         # Sign and publish to registry
+
+Signature Files:
+  Signatures are stored as <file>.auths.json next to the artifact.
+  Contains identity, device, and signature information.
+
+Related:
+  auths sign    — Sign commits and other files
+  auths verify  — Verify signatures
+  auths trust   — Manage trusted identities"
+)]
 pub struct ArtifactCommand {
     #[command(subcommand)]
     pub command: ArtifactSubcommand,
@@ -334,9 +353,9 @@ mod tests {
             "test",
             "publish",
             "my-file.tar.gz",
-            "--ika",
+            "--key",
             "main",
-            "--dka",
+            "--device-key",
             "device-1",
             "--expires-in",
             "3600",

crates/auths-cli/src/commands/audit.rs

@@ -17,7 +17,24 @@ use std::path::PathBuf;
 #[derive(Parser, Debug, Clone)]
 #[command(
     name = "audit",
-    about = "Generate signing audit reports for compliance"
+    about = "Generate signing audit reports for compliance",
+    after_help = "Examples:
+  auths audit --repo ~/myproject         # Audit commits in a repo
+  auths audit --since 2026-01-01 --until 2026-03-31
+                                         # Audit a specific date range
+  auths audit --format html -o report.html
+                                         # Generate HTML report
+  auths audit --require-all-signed --exit-code
+                                         # Exit 1 if any unsigned commits found
+
+Output Formats:
+  table — Human-readable table (default)
+  json  — Machine-readable JSON
+  html  — Interactive HTML report
+
+Related:
+  auths verify  — Verify signatures on commits
+  auths status  — Check device status"
 )]
 pub struct AuditCommand {
     /// Path to the Git repository to audit (defaults to current directory).

crates/auths-cli/src/commands/auth.rs

@@ -17,6 +17,24 @@ use crate::ux::format::{JsonResponse, is_json_mode};
 
 /// Authenticate with external services using your auths identity.
 #[derive(Parser, Debug, Clone)]
+#[command(
+    about = "Authenticate with external services using your auths identity",
+    after_help = "Examples:
+  auths auth challenge --nonce abc123def456 --domain example.com
+                        # Sign an authentication challenge
+  auths auth challenge --nonce abc123def456
+                        # Sign challenge for default domain (auths.dev)
+
+Flow:
+  1. Service sends you a nonce
+  2. Run: auths auth challenge --nonce <nonce> --domain <domain>
+  3. Service verifies your signature against your DID
+
+Related:
+  auths id     — Manage your identity
+  auths sign   — Sign files and commits
+  auths verify — Verify signatures"
+)]
 pub struct AuthCommand {
     #[clap(subcommand)]
     pub subcommand: AuthSubcommand,

crates/auths-cli/src/commands/completions.rs

@@ -7,7 +7,27 @@ use std::io;
 
 /// Generate shell completions for auths.
 #[derive(Parser, Debug, Clone)]
-#[command(name = "completions", about = "Generate shell completions")]
+#[command(
+    name = "completions",
+    about = "Generate shell completions",
+    after_help = "Examples:
+  auths completions bash              # Print Bash completions
+  auths completions zsh               # Print Zsh completions
+  auths completions fish              # Print Fish completions
+  auths completions powershell        # Print PowerShell completions
+
+Installation:
+  Bash:      auths completions bash > ~/.local/share/bash-completion/completions/auths
+  Zsh:       auths completions zsh > ~/.zfunc/_auths
+  Fish:      auths completions fish > ~/.config/fish/completions/auths.fish
+  PowerShell: auths completions powershell > auths.ps1
+
+After installation, restart your shell or source the completion file.
+
+Related:
+  auths --help       — Show all commands
+  auths <command> -h — Show command help"
+)]
 pub struct CompletionsCommand {
     /// The shell to generate completions for.
     #[arg(value_enum)]