agent-skillboard 0.2.9 → 0.2.10

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.2.10 — 2026-07-03
+
+### Fixed
+
+- `sudo npm install -g agent-skillboard` now resolves `SUDO_USER` during
+  install-time setup so the SkillBoard guidance skill is written to the
+  invoking user's agent homes instead of `/root`.
+
+### Changed
+
+- Install docs and CLI help now describe both normal global npm installs and
+  sudo/system npm installs, including the distinction between agent-home setup
+  and npm's executable prefix.
+
 ## 0.2.9 — 2026-07-03
 
 ### Changed

package/README.md

@@ -93,6 +93,12 @@ AI/automation/operator details:
 npm install -g agent-skillboard
 ```
 
+If your system npm requires elevated permissions, `sudo npm install -g
+agent-skillboard` is also supported. In that flow, install-time setup resolves
+`SUDO_USER` and writes the user-level guidance skill under the invoking user's
+agent homes, while the `skillboard` binary still lands in the global prefix used
+by that npm command.
+
 The install-time setup writes a user-level `skillboard` guidance skill under
 detected agent homes. For Codex, detection includes `CODEX_HOME/skills`,
 `AGENTS_HOME/skills`, `~/.agents/skills`, and `~/.codex/skills`.

package/docs/install.md

@@ -29,6 +29,17 @@ AI/automation/operator details:
 npm install -g agent-skillboard
 ```
 
+If your system npm requires elevated permissions, this is also supported:
+
+```bash
+sudo npm install -g agent-skillboard
+```
+
+Under sudo, the postinstall setup resolves `SUDO_USER` and targets that user's
+agent homes instead of writing guidance under `/root`. The executable prefix is
+still decided by the npm command you run, so use the same npm/Node environment
+you expect to provide `skillboard` on `PATH`.
+
 The install-time setup writes a user-level SkillBoard guidance skill under
 detected agent homes such as `CODEX_HOME`, `AGENTS_HOME`, `CLAUDE_HOME`,
 `OPENCODE_HOME`, and `HERMES_HOME`. Codex detection also checks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Let AI agents pick and use allowed skills in each workflow.",
   "keywords": [
     "ai-agent",

package/src/cli.mjs

@@ -1548,7 +1548,9 @@ function helpText() {
     "",
     "After global install:",
     "  npm install -g agent-skillboard",
+    "  sudo npm install -g agent-skillboard is also supported when system npm requires it.",
     "  The package postinstall auto-runs agent-layer guidance setup for detected supported agents.",
+    "  Under sudo, setup targets SUDO_USER's agent homes while npm still controls the binary prefix.",
     "  Run skillboard setup later after adding another supported agent or when install scripts were skipped.",
     "",
     "AI/automation operations:",

package/src/lifecycle-cli.mjs

@@ -1,12 +1,15 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline";
+import { promisify } from "node:util";
 import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
 import { initProject } from "./init.mjs";
 import { uninstallProject } from "./uninstall.mjs";
 
 const AGENT_INTEGRATION_START = "<!-- BEGIN SKILLBOARD AGENT INTEGRATION -->";
 const AGENT_INTEGRATION_END = "<!-- END SKILLBOARD AGENT INTEGRATION -->";
+const execFileAsync = promisify(execFile);
 
 export async function runInitCommand(options, stdout, runtime = defaultRuntime()) {
   const root = resolve(options.get("dir") ?? ".");
@@ -218,7 +221,7 @@ function defaultRuntime() {
 
 async function agentSetupTargets(options, runtime) {
   const env = runtime.env ?? process.env;
-  const home = env.HOME ?? env.USERPROFILE;
+  const home = await resolveSetupHome(env, runtime);
   const requested = readCsv(options.get("agent"));
   const supported = new Set(supportedAgentNames());
   const names = requested.length === 0 ? supportedAgentNames() : requested;
@@ -232,6 +235,79 @@ async function agentSetupTargets(options, runtime) {
   return targets;
 }
 
+async function resolveSetupHome(env, runtime) {
+  const explicit = nonEmpty(env.SKILLBOARD_SETUP_HOME);
+  if (explicit !== null) {
+    return explicit;
+  }
+  if (shouldUseSudoUserHome(env)) {
+    const sudoHome = nonEmpty(env.SUDO_HOME)
+      ?? await passwdHome(env.SUDO_USER, runtime.passwdPath ?? "/etc/passwd")
+      ?? await getentHome(env.SUDO_USER, env)
+      ?? await conventionalUserHome(env.SUDO_USER);
+    if (sudoHome !== null) {
+      return sudoHome;
+    }
+  }
+  return env.HOME ?? env.USERPROFILE;
+}
+
+function shouldUseSudoUserHome(env) {
+  const sudoUser = nonEmpty(env.SUDO_USER);
+  return process.platform !== "win32"
+    && sudoUser !== null
+    && sudoUser !== "root"
+    && (
+      env.SUDO_UID !== undefined
+      || env.SUDO_GID !== undefined
+      || env.USER === "root"
+      || env.LOGNAME === "root"
+      || env.HOME === "/root"
+    );
+}
+
+async function passwdHome(user, passwdPath) {
+  const text = await readFile(passwdPath, "utf8").catch(() => "");
+  for (const line of text.split("\n")) {
+    if (line.startsWith(`${user}:`)) {
+      return nonEmpty(line.split(":")[5]);
+    }
+  }
+  return null;
+}
+
+async function getentHome(user, env) {
+  try {
+    const { stdout } = await execFileAsync("getent", ["passwd", user], {
+      env,
+      timeout: 1000
+    });
+    return nonEmpty(stdout.trim().split(":")[5]);
+  } catch {
+    return null;
+  }
+}
+
+async function conventionalUserHome(user) {
+  const candidates = process.platform === "darwin"
+    ? [`/Users/${user}`]
+    : [`/home/${user}`];
+  for (const candidate of candidates) {
+    if (await exists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function exists(path) {
+  return access(path).then(() => true, () => false);
+}
+
+function nonEmpty(value) {
+  return value === undefined || value.trim() === "" ? null : value;
+}
+
 async function installAgentIntegration(targets) {
   const created = [];
   const updated = [];