chore: release v0.7.6 — bump version, update CHANGELOG

Author: johnstegeman

CHANGELOG.md

@@ -7,6 +7,41 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [v0.7.6] — 2026-03-26
+
+### Added
+
+- **`runner` accepts an array** — the `runner` field in `ai/config.toml` now accepts
+  either a string or an array, letting you invoke `agent-skills-cli` via a package
+  runner without a global install:
+  ```toml
+  [skills]
+  backend = "agent-skills"
+  runner  = ["bunx", "agent-skills-cli"]   # or ["npx", "agent-skills-cli"]
+  runner  = "skills"                        # string shorthand still works
+  ```
+
+- **`haven upgrade` sudo fallback** — when the upgrade binary write fails with a
+  permission error (e.g. haven is installed in `/usr/local/bin`), the command now
+  detects this, prints a clear message, and asks:
+  ```
+  error: Permission denied writing to /usr/local/bin/haven.
+  Retry with sudo? [y/N]
+  ```
+  If you confirm, it runs `sudo mv` + `sudo chmod 755` to complete the install.
+  The download and checksum steps are not repeated. The extracted binary is staged
+  in `/tmp` rather than a sibling `.new` file, so the permission error is caught
+  at the move step rather than the extract step.
+
+### Fixed
+
+- **`haven ai backends` no longer silently shows native** — previously, any error
+  loading `ai/config.toml` (e.g. a parse error or missing file) would silently fall
+  back to the native backend, making it appear as the active backend even when
+  another was configured. The error is now propagated so you see what went wrong.
+
+---
+
 ## [v0.7.5] — 2026-03-26
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "haven"
-version = "0.7.5"
+version = "0.7.6"
 edition = "2021"
 description = "AI-first dotfiles & environment manager"
 license = "MIT"

Cargo.toml

@@ -341,6 +341,17 @@ haven upgrade [--check] [--force]
 | `--check` | Check for update without installing. Exits 0 when up to date, 1 when update is available. |
 | `--force` | Install even if already on latest. |
 
+If haven is installed in a system directory (e.g. `/usr/local/bin`), the write
+will fail with a permission error. The command detects this and prompts:
+
+```
+error: Permission denied writing to /usr/local/bin/haven.
+Retry with sudo? [y/N]
+```
+
+Answering `y` runs `sudo mv` + `sudo chmod 755` to complete the install without
+repeating the download.
+
 ---
 
 ## `haven unmanaged`

docs/reference/commands.md

@@ -109,6 +109,46 @@ Run `haven ai discover` to auto-generate this file by scanning installed platfor
 
 ---
 
+## `ai/config.toml`
+
+Optional file that configures the AI skill backend. All fields have defaults;
+the file can be omitted entirely.
+
+```toml
+# ai/config.toml
+
+[skills]
+backend      = "native"   # "native" | "agent-skills" | "akm"
+runner       = "skills"   # binary name, path, or array (agent-skills backend only)
+timeout_secs = 120        # subprocess timeout in seconds (agent-skills backend only)
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `backend` | string | `"native"` | Skill backend to use. |
+| `runner` | string or array | `"skills"` | Binary (or program + args array) used to invoke agent-skills-cli. |
+| `timeout_secs` | integer | `120` | Timeout for agent-skills-cli subprocesses. |
+
+### Runner examples
+
+```toml
+# Global install (default)
+runner = "skills"
+
+# Custom path
+runner = "/usr/local/bin/skills"
+
+# Via bunx — no global install required
+runner = ["bunx", "agent-skills-cli"]
+
+# Via npx
+runner = ["npx", "agent-skills-cli"]
+```
+
+Run `haven ai backends` to see which backends are available and which is active.
+
+---
+
 ## `ai/skills/<name>/skill.toml`
 
 Declares a single AI skill.

docs/reference/configuration.md

@@ -2,9 +2,10 @@
 ///
 /// ```toml
 /// [skills]
-/// backend = "native"      # "native" | "agent-skills" | "akm"
-/// runner  = "skills"      # path to agent-skills-cli binary (agent-skills backend only)
-/// timeout_secs = 120      # subprocess timeout in seconds (agent-skills backend only)
+/// backend = "native"                        # "native" | "agent-skills" | "akm"
+/// runner  = "skills"                        # binary name or path (agent-skills backend only)
+/// runner  = ["bunx", "agent-skills-cli"]    # or an array: program + args prefix
+/// timeout_secs = 120                        # subprocess timeout in seconds (agent-skills backend only)
 /// ```
 ///
 /// When `ai/config.toml` is absent, all defaults apply (native backend).
@@ -35,9 +36,19 @@ impl BackendKind {
 #[derive(Debug, Clone)]
 pub struct AiConfig {
     pub backend: BackendKind,
-    /// Path or name of the agent-skills-cli runner binary (default: `"skills"`).
+    /// Runner command for the agent-skills-cli subprocess (default: `["skills"]`).
+    ///
+    /// The first element is the program, the rest are arguments prepended before the
+    /// subcommand. This lets users invoke via a package runner without a global install:
+    ///
+    /// ```toml
+    /// runner = ["bunx", "agent-skills-cli"]
+    /// runner = ["npx", "agent-skills-cli"]
+    /// runner = "/usr/local/bin/skills"   # string shorthand for single-element array
+    /// ```
+    ///
     /// Only used by `AgentSkills` backend (and future `Akm`).
-    pub runner: String,
+    pub runner: Vec<String>,
     /// Subprocess timeout in seconds (default: 120).
     /// Only used by `AgentSkills` backend (and future `Akm`).
     pub timeout_secs: u64,
@@ -47,7 +58,7 @@ impl Default for AiConfig {
     fn default() -> Self {
         AiConfig {
             backend: BackendKind::Native,
-            runner: "skills".to_string(),
+            runner: vec!["skills".to_string()],
             timeout_secs: 120,
         }
     }
@@ -77,10 +88,27 @@ struct RawAiConfig {
     skills: RawSkillsSection,
 }
 
+/// Accepts either `runner = "skills"` or `runner = ["bunx", "agent-skills-cli"]`.
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum RunnerValue {
+    Single(String),
+    Multi(Vec<String>),
+}
+
+impl From<RunnerValue> for Vec<String> {
+    fn from(v: RunnerValue) -> Self {
+        match v {
+            RunnerValue::Single(s) => vec![s],
+            RunnerValue::Multi(v) => v,
+        }
+    }
+}
+
 #[derive(Deserialize, Default)]
 struct RawSkillsSection {
     backend: Option<String>,
-    runner: Option<String>,
+    runner: Option<RunnerValue>,
     timeout_secs: Option<u64>,
 }
 
@@ -97,9 +125,16 @@ impl RawAiConfig {
             ),
         };
 
+        let runner = self.skills.runner
+            .map(Vec::from)
+            .unwrap_or_else(|| vec!["skills".to_string()]);
+        if runner.is_empty() {
+            anyhow::bail!("{}: 'runner' must not be an empty array", path_display);
+        }
+
         Ok(AiConfig {
             backend,
-            runner: self.skills.runner.unwrap_or_else(|| "skills".to_string()),
+            runner,
             timeout_secs: self.skills.timeout_secs.unwrap_or(120),
         })
     }
@@ -138,22 +173,42 @@ mod tests {
         write_config(&dir, "[skills]\nbackend = \"agent-skills\"\n");
         let cfg = AiConfig::load(dir.path()).unwrap();
         assert_eq!(cfg.backend, BackendKind::AgentSkills);
-        assert_eq!(cfg.runner, "skills");
+        assert_eq!(cfg.runner, vec!["skills"]);
         assert_eq!(cfg.timeout_secs, 120);
     }
 
     #[test]
-    fn ai_config_reads_custom_runner_and_timeout() {
+    fn ai_config_reads_string_runner() {
         let dir = TempDir::new().unwrap();
         write_config(
             &dir,
             "[skills]\nbackend = \"agent-skills\"\nrunner = \"/usr/local/bin/skills\"\ntimeout_secs = 60\n",
         );
         let cfg = AiConfig::load(dir.path()).unwrap();
-        assert_eq!(cfg.runner, "/usr/local/bin/skills");
+        assert_eq!(cfg.runner, vec!["/usr/local/bin/skills"]);
         assert_eq!(cfg.timeout_secs, 60);
     }
 
+    #[test]
+    fn ai_config_reads_array_runner() {
+        let dir = TempDir::new().unwrap();
+        write_config(
+            &dir,
+            "[skills]\nbackend = \"agent-skills\"\nrunner = [\"bunx\", \"agent-skills-cli\"]\n",
+        );
+        let cfg = AiConfig::load(dir.path()).unwrap();
+        assert_eq!(cfg.runner, vec!["bunx", "agent-skills-cli"]);
+    }
+
+    #[test]
+    fn ai_config_errors_on_empty_runner_array() {
+        let dir = TempDir::new().unwrap();
+        write_config(&dir, "[skills]\nbackend = \"agent-skills\"\nrunner = []\n");
+        let err = AiConfig::load(dir.path()).unwrap_err();
+        let msg = format!("{err:#}");
+        assert!(msg.contains("empty"), "error should mention empty array: {msg}");
+    }
+
     #[test]
     fn ai_config_errors_on_unknown_backend() {
         let dir = TempDir::new().unwrap();

src/ai_config.rs

@@ -1033,15 +1033,17 @@ struct AgentSkillsSearchEntry {
     stars: Option<u64>,
 }
 
-fn agentskills_search(runner: &str, query: &str, limit: usize) -> Result<Vec<SearchEntry>> {
-    let output = std::process::Command::new(runner)
+fn agentskills_search(runner: &[String], query: &str, limit: usize) -> Result<Vec<SearchEntry>> {
+    let runner_display = runner.join(" ");
+    let output = std::process::Command::new(&runner[0])
+        .args(&runner[1..])
         .args(["search", query, "--json", "--limit", &limit.to_string()])
         .output()
-        .with_context(|| format!("Failed to run '{}' — is agent-skills-cli installed?", runner))?;
+        .with_context(|| format!("Failed to run '{}' — is agent-skills-cli installed?", runner_display))?;
 
     if !output.status.success() {
         let stderr = String::from_utf8_lossy(&output.stderr);
-        anyhow::bail!("'{}' search failed: {}", runner, stderr.trim());
+        anyhow::bail!("'{}' search failed: {}", runner_display, stderr.trim());
     }
 
     let text = String::from_utf8(output.stdout).context("agent-skills-cli output was not UTF-8")?;
@@ -1161,8 +1163,7 @@ pub struct BackendsOptions<'a> {
 
 /// List all known skill backends and their availability on this machine.
 pub fn backends(opts: &BackendsOptions<'_>) -> Result<()> {
-    let config = crate::ai_config::AiConfig::load(opts.repo_root)
-        .unwrap_or_default();
+    let config = crate::ai_config::AiConfig::load(opts.repo_root)?;
     let active = config.backend.as_str();
     let infos = crate::skill_backend_factory::list_backends();