feat: add crates.io distribution with smart self-update detection

Add crates.io as a complementary distribution channel for the CLI.
The self-update mechanism now detects whether the CLI was installed via
cargo or prebuilt binary and adapts accordingly, using `cargo install`
for cargo-managed installations and GitHub Releases for binary installs.
Users can override with `--method=github` or `--method=cargo`.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: montfort

.github/workflows/release-cli.yml

@@ -168,3 +168,20 @@ jobs:
               gh release delete "$tag" --yes --cleanup-tag
             fi
           done
+
+  publish-crate:
+    name: Publish to crates.io
+    needs: [resolve-version, upload-to-release]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.resolve-version.outputs.tag }}
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Publish to crates.io
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
+        run: cargo publish --manifest-path cli/Cargo.toml

README.md

@@ -5,6 +5,7 @@
 **AI Governance Platform for Responsible Software Development**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Crates.io](https://img.shields.io/crates/v/devtrail-cli.svg)](https://crates.io/crates/devtrail-cli)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 [![Handbook](https://img.shields.io/badge/docs-Handbook-orange.svg)](dist/.devtrail/QUICK-REFERENCE.md)
 [![Strange Days Tech](https://img.shields.io/badge/by-Strange_Days_Tech-purple.svg)](https://strangedays.tech)
@@ -131,6 +132,8 @@ Or install from source with Cargo:
 cargo install devtrail-cli
 ```
 
+> **Note:** `devtrail update-cli` automatically detects how you installed the CLI. Prebuilt binary installs update from GitHub Releases; cargo installs update via `cargo install`. You can override with `--method=github` or `--method=cargo`.
+
 Then initialize in your project:
 
 ```bash

cli/Cargo.toml

@@ -6,10 +6,10 @@ description = "CLI tool for DevTrail - Documentation Governance for AI-Assisted
 license = "MIT"
 repository = "https://github.com/StrangeDaysTech/devtrail"
 homepage = "https://strangedays.tech"
-readme = "../README.md"
 keywords = ["devtrail", "documentation", "governance", "ai", "cli"]
 categories = ["command-line-utilities", "development-tools"]
 authors = ["Strange Days Tech, S.A.S."]
+include = ["src/**/*", "Cargo.toml", "Cargo.lock"]
 
 [[bin]]
 name = "devtrail"

cli/src/commands/about.rs

@@ -2,6 +2,7 @@ use anyhow::Result;
 use colored::Colorize;
 
 use crate::manifest::DistManifest;
+use crate::self_update::{self, InstallMethod};
 
 pub fn run() -> Result<()> {
     let version = env!("CARGO_PKG_VERSION");
@@ -30,6 +31,13 @@ pub fn run() -> Result<()> {
         }
     }
 
+    // Show install method
+    let install_label = match self_update::detect_install_method() {
+        InstallMethod::Cargo => "cargo (crates.io)",
+        InstallMethod::GitHubBinary => "prebuilt binary (GitHub Releases)",
+    };
+    println!("  {} {}", "Install:".dimmed(), install_label.dimmed());
+
     println!("  {}", description.dimmed());
     println!();
     println!("  {}  {}", "Author:".cyan(), authors);

cli/src/commands/update.rs

@@ -3,7 +3,7 @@ use colored::Colorize;
 
 use crate::utils;
 
-pub fn run() -> Result<()> {
+pub fn run(method: &str) -> Result<()> {
     let target = std::env::current_dir()?;
 
     // Update framework (skip if not initialized)
@@ -19,7 +19,7 @@ pub fn run() -> Result<()> {
     // Update CLI
     println!();
     println!("{}", "── CLI ──".bold());
-    if let Err(e) = super::update_cli::run() {
+    if let Err(e) = super::update_cli::run(method) {
         utils::warn(&format!("CLI update failed: {}", e));
     }
 

cli/src/commands/update_cli.rs

@@ -1,5 +1,8 @@
 use anyhow::Result;
 
-pub fn run() -> Result<()> {
-    crate::self_update::perform_update()
+use crate::self_update;
+
+pub fn run(method: &str) -> Result<()> {
+    let method = self_update::parse_method(method);
+    self_update::perform_update(method)
 }

cli/src/main.rs

@@ -37,11 +37,19 @@ enum Commands {
         path: String,
     },
     /// Update both framework and CLI to the latest version
-    Update,
+    Update {
+        /// Update method for the CLI binary: auto, github, or cargo
+        #[arg(long, default_value = "auto", value_parser = ["auto", "github", "cargo"])]
+        method: String,
+    },
     /// Update the DevTrail framework to the latest version
     UpdateFramework,
     /// Update the CLI binary to the latest version
-    UpdateCli,
+    UpdateCli {
+        /// Update method: auto (detect), github (prebuilt binary), or cargo (compile from source)
+        #[arg(long, default_value = "auto", value_parser = ["auto", "github", "cargo"])]
+        method: String,
+    },
     /// Remove DevTrail from the project
     Remove {
         /// Remove everything including user-generated documents (requires confirmation)
@@ -164,9 +172,9 @@ fn main() {
 
     let result = match cli.command {
         Commands::Init { path } => commands::init::run(&path),
-        Commands::Update => commands::update::run(),
+        Commands::Update { method } => commands::update::run(&method),
         Commands::UpdateFramework => commands::update_framework::run(),
-        Commands::UpdateCli => commands::update_cli::run(),
+        Commands::UpdateCli { method } => commands::update_cli::run(&method),
         Commands::Remove { full } => commands::remove::run(full),
         Commands::Validate { path, fix, staged } => commands::validate::run(&path, fix, staged),
         Commands::Audit {

cli/src/self_update.rs

@@ -6,8 +6,134 @@ use crate::download;
 use crate::platform;
 use crate::utils;
 
-/// Perform the CLI self-update
-pub fn perform_update() -> Result<()> {
+/// How the CLI was installed
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum InstallMethod {
+    /// Installed via `cargo install devtrail-cli`
+    Cargo,
+    /// Installed via prebuilt binary from GitHub Releases
+    GitHubBinary,
+}
+
+/// Check if a path indicates a cargo installation (contains `.cargo/bin/`)
+fn path_indicates_cargo(path: &Path) -> bool {
+    path.components().any(|c| c.as_os_str() == ".cargo")
+        && path
+            .parent()
+            .and_then(|p| p.file_name())
+            .map(|name| name == "bin")
+            .unwrap_or(false)
+}
+
+/// Detect the installation method based on the executable path
+pub fn detect_install_method() -> InstallMethod {
+    std::env::current_exe()
+        .ok()
+        .and_then(|p| p.canonicalize().ok().or(Some(p)))
+        .filter(|p| path_indicates_cargo(p))
+        .map(|_| InstallMethod::Cargo)
+        .unwrap_or(InstallMethod::GitHubBinary)
+}
+
+/// Parse a method string from the CLI flag into an InstallMethod override
+pub fn parse_method(method: &str) -> Option<InstallMethod> {
+    match method {
+        "cargo" => Some(InstallMethod::Cargo),
+        "github" => Some(InstallMethod::GitHubBinary),
+        _ => None, // "auto" or anything else → auto-detect
+    }
+}
+
+/// Perform the CLI self-update, using the specified method or auto-detecting
+pub fn perform_update(method_override: Option<InstallMethod>) -> Result<()> {
+    let method = method_override.unwrap_or_else(detect_install_method);
+
+    match method {
+        InstallMethod::Cargo => perform_cargo_update(),
+        InstallMethod::GitHubBinary => perform_github_update(),
+    }
+}
+
+/// Update via `cargo install --force devtrail-cli`
+fn perform_cargo_update() -> Result<()> {
+    let current_version = env!("CARGO_PKG_VERSION");
+    utils::info(&format!("Current version: cli-{}", current_version));
+    println!(
+        "  {} {}",
+        "Install method:".dimmed(),
+        "cargo (crates.io)".cyan()
+    );
+
+    // Check for newer version via GitHub API
+    utils::info("Checking for updates...");
+    let release = download::get_latest_release_full()?;
+    let tag_version = download::strip_tag_prefix(&release.tag_name);
+
+    println!(
+        "  {} {}",
+        "Latest version:".dimmed(),
+        release.tag_name.green()
+    );
+
+    let current =
+        semver::Version::parse(current_version).context("Failed to parse current version")?;
+    let latest =
+        semver::Version::parse(tag_version).context("Failed to parse release version")?;
+
+    if latest <= current {
+        utils::success(&format!(
+            "CLI is already at the latest version (cli-{})",
+            current_version
+        ));
+        return Ok(());
+    }
+
+    // Verify cargo is available
+    let cargo_available = std::process::Command::new("cargo")
+        .arg("--version")
+        .output()
+        .is_ok();
+
+    if !cargo_available {
+        utils::warn("cargo not found in PATH. Run the following command manually:");
+        println!(
+            "\n  {}\n",
+            "cargo install --force devtrail-cli".yellow().bold()
+        );
+        bail!("cargo is not available in PATH");
+    }
+
+    // Confirm with user
+    let confirm = dialoguer::Confirm::new()
+        .with_prompt(format!(
+            "Update from cli-{current_version} to cli-{tag_version} via cargo?"
+        ))
+        .default(true)
+        .interact()?;
+
+    if !confirm {
+        utils::info("Update cancelled.");
+        return Ok(());
+    }
+
+    utils::info("Compiling from source, this may take a few minutes...");
+
+    let status = std::process::Command::new("cargo")
+        .args(["install", "--force", "devtrail-cli"])
+        .status()
+        .context("Failed to run cargo install")?;
+
+    if status.success() {
+        utils::success(&format!("CLI updated to cli-{}!", tag_version));
+    } else {
+        bail!("cargo install failed with exit code: {}", status);
+    }
+
+    Ok(())
+}
+
+/// Update via prebuilt binary from GitHub Releases
+fn perform_github_update() -> Result<()> {
     let current_version = env!("CARGO_PKG_VERSION");
     utils::info(&format!("Current version: cli-{}", current_version));
 

docs/i18n/es/README.md

@@ -5,6 +5,7 @@
 **Plataforma de Gobernanza de IA para Desarrollo de Software Responsable**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../../LICENSE)
+[![Crates.io](https://img.shields.io/crates/v/devtrail-cli.svg)](https://crates.io/crates/devtrail-cli)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 [![Handbook](https://img.shields.io/badge/docs-Handbook-orange.svg)](../../../dist/.devtrail/QUICK-REFERENCE.md)
 [![Strange Days Tech](https://img.shields.io/badge/by-Strange_Days_Tech-purple.svg)](https://strangedays.tech)
@@ -131,6 +132,8 @@ O instalar desde el código fuente con Cargo:
 cargo install devtrail-cli
 ```
 
+> **Nota:** `devtrail update-cli` detecta automáticamente cómo instalaste el CLI. Las instalaciones con binario precompilado se actualizan desde GitHub Releases; las instalaciones con cargo se actualizan via `cargo install`. Puedes forzar el método con `--method=github` o `--method=cargo`.
+
 Luego inicializa en tu proyecto:
 
 ```bash