feat: add auths pair as a top-level command

Promote device pairing to a first-class command visible in `auths --help`.
Pairing is something most users do immediately after `auths init`, so it
should be discoverable without `--help-all`. The existing `auths device pair`
path continues to work.

Also fixes tutorial text to match actual CLI syntax (`auths pair` and
`auths pair --join CODE`).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bordumb

crates/auths-cli/README.md

@@ -13,6 +13,13 @@ auths verify HEAD
 
 That's it. `auths init` generates keys, creates your identity, and configures Git signing.
 
+### Link another device
+
+```bash
+auths pair                         # On existing device — shows QR/code
+auths pair --join ABC123           # On new device — enter the code
+```
+
 ## The Basics
 
 ### `auths sign` — Sign a commit or artifact

crates/auths-cli/src/cli.rs

@@ -12,6 +12,7 @@ use crate::commands::completions::CompletionsCommand;
 use crate::commands::config::ConfigCommand;
 use crate::commands::debug::DebugCmd;
 use crate::commands::device::DeviceCommand;
+use crate::commands::device::pair::PairCommand;
 use crate::commands::doctor::DoctorCommand;
 use crate::commands::emergency::EmergencyCommand;
 use crate::commands::git::GitCommand;
@@ -91,6 +92,7 @@ pub enum RootCommand {
     Whoami(WhoamiCommand),
     Tutorial(LearnCommand),
     Doctor(DoctorCommand),
+    Pair(PairCommand),
     #[command(hide = true)]
     Completions(CompletionsCommand),
     #[command(hide = true)]

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

@@ -10,6 +10,12 @@ use crate::commands::executable::ExecutableCommand;
 use crate::config::CliConfig;
 use anyhow::Result;
 
+impl ExecutableCommand for PairCommand {
+    fn execute(&self, ctx: &CliConfig) -> Result<()> {
+        handle_pair(self.clone(), &ctx.env_config)
+    }
+}
+
 impl ExecutableCommand for DeviceCommand {
     fn execute(&self, ctx: &CliConfig) -> Result<()> {
         handle_device(

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

@@ -476,11 +476,11 @@ fn section_linking_device() -> Result<()> {
     println!("  To link a new device:");
     println!();
     println!("    {} On your existing device:", "1.".cyan());
-    println!("       {}", "$ auths pair start".cyan());
+    println!("       {}", "$ auths pair".cyan());
     println!("       {}", "Scan this QR code or enter: ABC123".dimmed());
     println!();
     println!("    {} On your new device:", "2.".cyan());
-    println!("       {}", "$ auths pair join --code ABC123".cyan());
+    println!("       {}", "$ auths pair --join ABC123".cyan());
     println!();
     println!(
         "  This creates an {} that authorizes the new device",

crates/auths-cli/src/main.rs

@@ -68,6 +68,7 @@ fn run() -> Result<()> {
         RootCommand::Whoami(cmd) => cmd.execute(&ctx),
         RootCommand::Tutorial(cmd) => cmd.execute(&ctx),
         RootCommand::Doctor(cmd) => cmd.execute(&ctx),
+        RootCommand::Pair(cmd) => cmd.execute(&ctx),
         RootCommand::Completions(cmd) => cmd.execute(&ctx),
         RootCommand::Emergency(cmd) => cmd.execute(&ctx),
         RootCommand::Id(cmd) => cmd.execute(&ctx),