agent-skillboard 0.2.9 → 0.2.11

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.2.11 — 2026-07-03
+
+### Fixed
+
+- Codex setup now creates and installs into `~/.agents/skills` when the user
+  already has a `~/.agents` home, even if `~/.agents/skills` did not exist yet
+  and `~/.codex/skills` was also detected.
+
+## 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,9 +93,17 @@ 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`.
+If `~/.agents` already exists, setup creates `~/.agents/skills` because that is
+the shared Codex-visible skill tree in LazyCodex-style environments.
 It does not create `skillboard.config.yaml`,
 `.skillboard/`, `AGENTS.md`, or `CLAUDE.md` in projects.
 No separate setup command is required after a normal global install.

package/docs/install.md

@@ -29,10 +29,24 @@ 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
 `~/.agents/skills` and `~/.codex/skills`.
+If `~/.agents` exists but `~/.agents/skills` does not, setup creates the
+`skills` directory and installs the guidance skill there so Codex profiles that
+read the shared agent skill tree can see SkillBoard after restart.
 No separate setup command is required after a normal global install.
 
 Run `skillboard setup` later when you add another supported agent, enable a new

package/package.json

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

package/src/agent-skill-roots.mjs

@@ -12,7 +12,11 @@ export async function detectedAgentSkillRoots(agent, home = homedir(), env = pro
   const candidates = await agentSkillRootCandidates(agent, home, env);
   const detected = [];
   for (const candidate of candidates) {
-    if (candidate.explicit || await exists(candidate.skillRoot)) {
+    if (
+      candidate.explicit
+      || await exists(candidate.skillRoot)
+      || candidate.detectWhenExists !== undefined && await exists(candidate.detectWhenExists)
+    ) {
       detected.push(candidate);
     }
   }
@@ -41,10 +45,11 @@ export async function agentSkillRootCandidates(agent, home = homedir(), env = pr
   const normalized = normalizeAgent(agent);
   const xdgConfig = env.XDG_CONFIG_HOME ?? join(home, ".config");
   if (normalized === "codex") {
+    const agentsHome = join(home, ".agents");
     return uniqueCandidates([
       env.CODEX_HOME === undefined ? null : candidate(join(env.CODEX_HOME, "skills"), "CODEX_HOME/skills", true, false),
       env.AGENTS_HOME === undefined ? null : candidate(join(env.AGENTS_HOME, "skills"), "AGENTS_HOME/skills", true, false),
-      candidate(join(home, ".agents", "skills"), "~/.agents/skills", false, false),
+      candidate(join(agentsHome, "skills"), "~/.agents/skills", false, false, agentsHome),
       candidate(join(home, ".codex", "skills"), "~/.codex/skills", false, true)
     ]);
   }
@@ -79,8 +84,8 @@ function normalizeAgent(agent) {
   return agent;
 }
 
-function candidate(skillRoot, source, explicit, fallback) {
-  return { skillRoot, source, explicit, fallback };
+function candidate(skillRoot, source, explicit, fallback, detectWhenExists) {
+  return { skillRoot, source, explicit, fallback, detectWhenExists };
 }
 
 function fallbackCandidate(candidates) {

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 = [];