agent-skillboard 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.2.12 — 2026-07-03
+
+### Changed
+
+- Install help and docs now state that global npm installs and updates rerun
+  agent-layer setup automatically, refreshing managed guidance files and
+  installing into newly detected supported agent roots.
+
+### Fixed
+
+- Added regression coverage for update-style postinstall runs so managed
+  SkillBoard guidance is refreshed and newly detected agent roots are installed
+  during the same lifecycle pass.
+
+## 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

package/README.md

@@ -102,9 +102,13 @@ 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.
+No separate setup command is required after a normal global install or update:
+npm lifecycle scripts rerun the agent-home scan, refresh managed SkillBoard
+guidance files, and add newly detected supported agent roots.
 
 Run `skillboard setup --agent codex,claude,opencode,hermes --yes` later only
 after adding another supported agent, enabling a new agent home, or installing

package/bin/postinstall.mjs

@@ -7,14 +7,14 @@ if (isTruthy(process.env.SKILLBOARD_SKIP_POSTINSTALL)) {
 }
 
 process.stderr.write(`${[
-  "SkillBoard installed.",
+  "SkillBoard installed or updated.",
   "It does not change agent configs or project files.",
   ""
 ].join("\n")}\n`);
 
 if (!shouldAutoSetup(process.env)) {
   process.stderr.write(`${[
-    "Global installs auto-run agent setup when supported agent homes are detected.",
+    "Global installs and updates auto-run agent setup when supported agent homes are detected.",
     "Run skillboard setup later after adding another supported agent:",
     "  skillboard setup",
     "",
@@ -40,7 +40,7 @@ try {
     packageSpec: "agent-skillboard"
   });
   if (exitCode === 0) {
-    process.stderr.write("Agent setup complete. Run skillboard setup later after adding another supported agent.\n");
+    process.stderr.write("Agent setup complete. Package updates rerun this setup automatically; run skillboard setup later after adding another supported agent.\n");
   } else {
     process.stderr.write("Agent setup did not find supported agent homes. Run skillboard setup after installing or enabling a supported agent.\n");
   }

package/docs/install.md

@@ -44,7 +44,13 @@ 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`.
-No separate setup command is required after a normal global install.
+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 or update.
+When npm runs lifecycle scripts, package updates rerun the agent-home scan,
+refresh managed SkillBoard guidance files, and add newly detected supported
+agent roots.
 
 Run `skillboard setup` later when you add another supported agent, enable a new
 agent home, intentionally skipped lifecycle scripts, or need to repair the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "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

@@ -1549,7 +1549,7 @@ 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.",
+    "  The package postinstall auto-runs agent-layer guidance setup on install and update.",
     "  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.",
     "",