@knowttl/mg-axi 0.1.8 → 0.1.9

package/dist/catalogue.js

@@ -2875,9 +2875,10 @@ export function operationFor(leaf, version) {
     const inventory = JSON.parse(readFileSync(new URL("../inventory/operations.json", import.meta.url), "utf8"));
     return inventory.operations.find((row) => row.id === `${version}:${leaf.operation}`);
 }
-// Next-step hints shared by the no-args home view and the installable
+// Base next-step hints shared by the no-args home view and the installable
 // skill, so the two cannot drift apart. home() prints them alongside live
-// profile status; skillDocument() in docs.ts reprints them.
+// profile status; skillDocument() in docs.ts reprints them. localHome() in
+// cli.ts may append one conditional skill install hint (see skill-hint.ts).
 export const HOME_HELP = ["npx -y @knowttl/mg-axi setup", "npx -y @knowttl/mg-axi doctor", "npx -y @knowttl/mg-axi entra user list --help", "npx -y @knowttl/mg-axi entra user show --help", "npx -y @knowttl/mg-axi entra group list --help", "npx -y @knowttl/mg-axi entra group member list --help", "npx -y @knowttl/mg-axi entra application list --help", "npx -y @knowttl/mg-axi entra service-principal list --help", "npx -y @knowttl/mg-axi entra conditional-access policy list --help", "npx -y @knowttl/mg-axi api get --help"];
 // A useful local status, without treating unavailable tenant summaries as zeros.
 export function home() {

package/dist/cli.js

@@ -6,6 +6,7 @@ import { AxiError, installSessionStartHooks, runAxiCli } from "axi-sdk-js";
 import { LEAVES, home, leafHelp, operationFor, resolveCommand, DESCRIPTION, TOP_LEVEL_HELP } from "./catalogue.js";
 import { VERSION } from "./version.js";
 import { Profiles } from "./profiles.js";
+import { skillHint } from "./skill-hint.js";
 import { authStatus } from "./auth-status.js";
 import { redactSecrets } from "./redact.js";
 import { GraphSession, MAX_CURSOR_BYTES } from "./graph-session.js";
@@ -66,6 +67,10 @@ function localHome(name, config) {
             output.profile = "unavailable: no default profile selected";
     }
     output.help.unshift("npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi auth login --help");
+    // Point agents at the installable skill until it is installed for their host.
+    const hint = skillHint();
+    if (hint !== undefined)
+        output.help.push(hint);
     return output;
 }
 // One dispatch for the hook installer: resolve the sibling hook entry point

package/dist/docs.js

@@ -135,9 +135,11 @@ export function skillDescription() {
     const writes = skillWriteLabels();
     return `Inspect Microsoft Entra ${areas.join(", ")} and run ${writes.length} gated writes (${writes.join(", ")}) through token-efficient TOON output.`;
 }
-// Next-step hints printed by the no-args home view. The two leading entries mirror the
+// Base next-step hints printed by the no-args home view. The two leading entries mirror the
 // profile/login hints localHome() in cli.ts prepends to HOME_HELP; the
 // rest is HOME_HELP verbatim, so skill and home view cannot drift apart.
+// localHome() may append one conditional skill install hint from skill-hint.ts
+// when the skill is missing for the current host; the installed skill omits it.
 export function skillHomeHints() {
     return ["npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi auth login --help", ...HOME_HELP];
 }

package/dist/skill-hint.js

@@ -0,0 +1,138 @@
+// One-line skill install hint for the no-args home view. Detects the agent
+// host from its documented environment marker and checks whether the mg-axi
+// skill is already installed for that host, at user, project (working
+// directory upwards) and system level. File-existence checks only: this never
+// installs, writes, fails or touches the network.
+//
+// The check looks only at the detected host's row, so one host's copy never
+// hides another host's hint. Each row lists every documented skill folder
+// that host loads, verified against the real hosts:
+// - Claude Code reads its config directory ($CLAUDE_CONFIG_DIR or ~/.claude,
+//   per its binary) plus ~/.agents/skills and .agents/skills (per its
+//   binary); project .claude/skills loads from the working directory up to
+//   the repository root (per https://code.claude.com/docs/en/skills). When
+//   the working directory is inside a linked git worktree whose root has no
+//   .claude/skills directory, Claude Code (v2.1.277+) falls back to the main
+//   checkout's project skills (per https://code.claude.com/docs/en/worktrees).
+// - Codex reads $HOME/.agents/skills and .agents/skills (cwd to repo root)
+//   per https://learn.chatgpt.com/docs/build-skills.md, plus
+//   $CODEX_HOME/skills (default ~/.codex/skills, per its binary and the
+//   skills-CLI registry) and the documented /etc/codex/skills admin folder.
+// - Pi reads its user/project skills directories plus the Agent Skills
+//   locations ~/.agents/skills/ and .agents/skills/ (ancestors to the repo
+//   root) per its skills.md.
+// - OpenCode reads its config directory ($OPENCODE_CONFIG_DIR,
+//   $XDG_CONFIG_HOME or ~/.config, per its binary and CLI docs) plus
+//   ~/.claude/skills, ~/.agents/skills, .opencode/skills, .claude/skills and
+//   .agents/skills (project paths walk up to the git worktree) per
+//   https://opencode.ai/docs/skills/.
+//
+// Only a direct-child <folder>/mg-axi/SKILL.md counts as installed. Folders
+// listed in host settings files (for example Pi settings.json) and recursive
+// nested layouts are a documented limitation and are deliberately not
+// implemented.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+export const SKILL_NAME = "mg-axi";
+export const SKILL_INSTALL_COMMAND = `npx skills add knowttl/${SKILL_NAME} --skill ${SKILL_NAME}`;
+function skillFile(dir) {
+    return join(dir, SKILL_NAME, "SKILL.md");
+}
+function resolveHome(env) {
+    return env.HOME ?? env.USERPROFILE ?? homedir();
+}
+export function skillHostRows(env, home) {
+    const agentsUser = join(home, ".agents", "skills");
+    const agentsProject = join(".agents", "skills");
+    return [
+        {
+            name: "claude-code",
+            userDirs: [join(env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"), "skills"), agentsUser],
+            projectDirs: [join(".claude", "skills"), agentsProject],
+            systemDirs: [],
+        },
+        {
+            name: "codex",
+            userDirs: [join(env.CODEX_HOME ?? join(home, ".codex"), "skills"), agentsUser],
+            projectDirs: [agentsProject],
+            systemDirs: ["/etc/codex/skills"],
+        },
+        {
+            name: "pi",
+            userDirs: [join(home, ".pi", "agent", "skills"), agentsUser],
+            projectDirs: [join(".pi", "skills"), agentsProject],
+            systemDirs: [],
+        },
+        {
+            name: "opencode",
+            userDirs: [
+                join(env.OPENCODE_CONFIG_DIR ?? env.XDG_CONFIG_HOME ?? join(home, ".config"), "opencode", "skills"),
+                join(home, ".claude", "skills"),
+                agentsUser,
+            ],
+            projectDirs: [join(".opencode", "skills"), join(".claude", "skills"), agentsProject],
+            systemDirs: [],
+        },
+    ];
+}
+// Marker variables each host sets for its own child processes, verified
+// against the real hosts: CLAUDECODE (Claude Code docs), CODEX_THREAD_ID /
+// CODEX_SESSION_ID (codex shell_environment.rs), PI_CODING_AGENT (pi docs),
+// OPENCODE (opencode startup middleware, inherited by its shell children).
+export function detectSkillHost(env, home) {
+    const rows = skillHostRows(env, home);
+    if (env.CLAUDECODE !== undefined)
+        return rows.find(row => row.name === "claude-code");
+    if (env.CODEX_THREAD_ID !== undefined || env.CODEX_SESSION_ID !== undefined)
+        return rows.find(row => row.name === "codex");
+    if (env.PI_CODING_AGENT !== undefined)
+        return rows.find(row => row.name === "pi");
+    if (env.OPENCODE !== undefined)
+        return rows.find(row => row.name === "opencode");
+    return undefined;
+}
+// Main-checkout fallback for a linked git worktree: <worktree>/.git is a file
+// reading "gitdir: <main>/.git/worktrees/<name>". Applies only when the
+// worktree root has no .claude/skills directory of its own.
+function claudeWorktreeSkill(fromDir) {
+    for (let dir = resolve(fromDir);; dir = dirname(dir)) {
+        let gitdir;
+        try {
+            const text = readFileSync(join(dir, ".git"), "utf8");
+            const prefix = "gitdir: ";
+            if (text.startsWith(prefix))
+                gitdir = resolve(dir, text.slice(prefix.length).trim());
+        }
+        catch {
+            gitdir = undefined;
+        }
+        if (gitdir !== undefined) {
+            const splitAt = gitdir.replace(/\\/g, "/").indexOf("/.git/worktrees/");
+            if (splitAt === -1 || existsSync(join(dir, ".claude", "skills")))
+                return false;
+            return existsSync(skillFile(join(gitdir.slice(0, splitAt), ".claude", "skills")));
+        }
+        if (existsSync(join(dir, ".git")) || dirname(dir) === dir)
+            return false;
+    }
+}
+export function skillInstalled(row, fromDir) {
+    if ([...row.userDirs, ...row.systemDirs].some(dir => existsSync(skillFile(dir))))
+        return true;
+    for (let dir = resolve(fromDir);; dir = dirname(dir)) {
+        if (row.projectDirs.some(projectDir => existsSync(skillFile(join(dir, projectDir)))))
+            return true;
+        if (dirname(dir) === dir)
+            break;
+    }
+    if (row.name === "claude-code")
+        return claudeWorktreeSkill(fromDir);
+    return false;
+}
+export function skillHint(env = process.env, fromDir = process.cwd()) {
+    const host = detectSkillHost(env, resolveHome(env));
+    if (host === undefined || skillInstalled(host, fromDir))
+        return undefined;
+    return SKILL_INSTALL_COMMAND;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/mg-axi",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Agent-facing Microsoft Graph CLI, read-only by default",
   "type": "module",
   "bin": {