@kal-elsam/kairo-runtime 0.1.1 → 0.1.3

package/README.md

@@ -51,14 +51,14 @@ curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/inst
 The bootstrap installer:
 
 - requires Node.js 20.12+ and npm
-- runs `@kal-elsam/kairo-runtime` via `npx` (or `npm exec`)
-- ends with `kairo setup --dry-run` by default (no agent configs, no `~/.harness` writes)
+- installs `@kal-elsam/kairo-runtime` globally (`kairo` CLI)
+- runs `kairo setup --dry-run` by default (no agent configs, no `~/.harness` writes)
 - never uses `sudo`, never modifies shell profiles, and never installs AI apps
 
 Apply the plan when you are ready:
 
 ```bash
-npx @kal-elsam/kairo-runtime --yes
+kairo setup --yes
 # or
 curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --yes
 ```
@@ -66,8 +66,8 @@ curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/inst
 CI, scripts, and advanced non-interactive configure:
 
 ```bash
-npx @kal-elsam/kairo-runtime install --agents cursor,codex --yes
-npx @kal-elsam/kairo-runtime setup --yes --agents all
+kairo install --agents cursor,codex --yes
+kairo setup --yes --agents all
 ```
 
 Passthrough examples:
@@ -83,11 +83,11 @@ Control plane:
 kairo status
 kairo sync
 kairo upgrade --dry-run
-npx @kal-elsam/kairo-runtime@latest setup --yes
+kairo setup --yes
 ```
 
 After `install.sh --yes`, verify health with `kairo status`, repair drift with `kairo sync`,
-and move to the latest package with `npx @kal-elsam/kairo-runtime@latest setup --yes`.
+and preview upgrades with `kairo upgrade --dry-run`.
 
 ### Version and updates
 
@@ -737,7 +737,7 @@ git fetch --tags origin
 git fetch origin main
 npm run release:published -- --version 0.1.1 --tag kairo-runtime-v0.1.1
 npm run smoke:registry -- --version 0.1.1
-npm run smoke:installer -- --version 0.1.1
+npm run smoke:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
 npm run smoke:bridge
 ```
 
@@ -760,7 +760,13 @@ Without `--tag`, provenance checks fall back to `v${version}` (legacy tags).
 
 `smoke:registry` installs `@kal-elsam/kairo-runtime` from the npm registry (not the local tarball) into a throwaway workspace with a fake `HARNESS_HOME` and npm cache, then runs the recommended flow via `kairo`: `setup --dry-run`, `setup --yes`, `status`, drift simulation, `sync`, `status --json` (expects `overall=ok`), and `uninstall`. Use `latest` by default, pin with `--version x.y.z`, or override with `--package`.
 
-`smoke:installer` validates the public one-liner path: `curl .../install.sh | sh` against GitHub `raw` and the npm registry with isolated `HARNESS_HOME`. Preview must not write `~/.harness`; `--yes --agents all` must reach `kairo status --json` with `overall=ok`, then `kairo uninstall` must remove managed sections. Pin with `--version x.y.z` after publish.
+`smoke:installer` validates the public one-liner path: `curl .../install.sh | sh` against GitHub `raw` and the npm registry with isolated `HARNESS_HOME`. Preview must not write `~/.harness`; `--yes --agents all` must reach `kairo status --json` with `overall=ok`, then `kairo uninstall` must remove managed sections. Pin with `--version x.y.z` after publish. For package-aware Kairo Runtime tags, pass the git tag explicitly:
+
+```bash
+npm run smoke:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
+```
+
+Without `--tag`, the install script resolves from legacy `v${version}` tags.
 
 Suggested first Kairo Runtime tag after bootstrap: `kairo-runtime-v0.1.1`.
 

package/global-template/components/catalog.json

@@ -20,6 +20,32 @@
         "claude": "- In repos with workspace harness: repo `AGENTS.md` wins over `CLAUDE.md` pointers.",
         "opencode": "- In repos with workspace harness: also read `.opencode/` SDD assets when present."
       }
+    },
+    {
+      "id": "engram-memory",
+      "label": "Engram Memory",
+      "version": "1.0.0",
+      "defaultEnabled": false,
+      "assetFiles": ["memory.md"],
+      "adapterHints": {
+        "cursor": "- Engram MCP (`mem_*` tools) is not auto-installed; configure in Cursor MCP settings when ready.",
+        "codex": "- Engram MCP is not auto-installed; add MCP server config when ready.",
+        "claude": "- Engram MCP is not auto-installed; add MCP server config when ready.",
+        "opencode": "- Engram MCP is not auto-installed; add MCP server config when ready."
+      }
+    },
+    {
+      "id": "graphify-context",
+      "label": "Graphify Context",
+      "version": "1.0.0",
+      "defaultEnabled": false,
+      "assetFiles": ["context-graph.md"],
+      "adapterHints": {
+        "cursor": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH.",
+        "codex": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH.",
+        "claude": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH.",
+        "opencode": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH."
+      }
     }
   ]
 }

package/global-template/components/engram-memory/memory.md

@@ -0,0 +1,58 @@
+# Engram Memory Contract
+
+> Managed by `@kal-elsam/kairo-runtime` component `engram-memory`.
+
+## Role
+
+Engram is an optional external memory layer. It indexes decisions, bugs, and
+conventions across sessions. It does not replace the repository as source of
+truth.
+
+## Authority order
+
+```txt
+1. Current user instruction
+2. Repository AGENTS.md (when working inside a repo)
+3. Repository docs/ai/ and docs/specs/
+4. Engram (persistent memory)
+5. Graphify (context graph)
+```
+
+If Engram contradicts AGENTS.md or repo docs, the repo wins. Update or discard
+stale memory instead of following it blindly.
+
+## When to search memory
+
+Search Engram before:
+
+- Starting a non-trivial task or a standard/complex spec.
+- Diagnosing a bug that feels familiar or recurring.
+- Proposing a new architecture or convention.
+- Resuming work after context compaction or a new session.
+- Repeating a loop task (see loop-retrospective guidance when present).
+
+Skip memory search for trivial changes (typos, formatting, comments) or tasks
+fully specified in an active spec.
+
+## When to save memory
+
+Save proactively after:
+
+- Architecture or policy decisions (with reasoning, not just the outcome).
+- Bug root causes that may recur.
+- Undocumented conventions discovered in code review.
+- Loop retrospectives and discarded approaches (with why they were rejected).
+
+Do not save secrets, credentials, PII, ephemeral debug output, or content
+already documented in AGENTS.md or docs/ai/.
+
+## MCP tools
+
+Engram is not bundled with Kairo Runtime. Configure Engram MCP tools
+(`mem_search`, `mem_save`, etc.) in your agent when you want persistent memory.
+Kairo only ships the contract and health checks — not the MCP server itself.
+
+## Decision traceability
+
+Important decisions belong in `docs/ai/decision-log.md` or an ADR. Engram
+indexes; the repo certifies.

package/global-template/components/graphify-context/context-graph.md

@@ -0,0 +1,58 @@
+# Graphify Context Contract
+
+> Managed by `@kal-elsam/kairo-runtime` component `graphify-context`.
+
+## Role
+
+Graphify is an optional context graph for architecture navigation. It maps
+modules, dependencies, features, and risks. It does not replace reading code or
+repo documentation.
+
+## Authority order
+
+```txt
+1. Current user instruction
+2. Repository AGENTS.md (when working inside a repo)
+3. Repository docs/ai/ and docs/specs/
+4. Engram (persistent memory)
+5. Graphify (context graph)
+```
+
+If the graph contradicts code or repo docs, investigate the code first. Regenerate
+the graph with `graphify update .` — never edit graph artifacts by hand.
+
+## When to consult Graphify
+
+Before answering architecture or cross-module questions:
+
+1. Read `graphify-out/GRAPH_REPORT.md` for god nodes and community structure.
+2. If `graphify-out/wiki/index.md` exists, navigate it instead of scanning raw files.
+3. For "how does X relate to Y", prefer `graphify query`, `graphify path`, or
+   `graphify explain` over broad grep when the graph is fresh.
+
+Before modifying code in an unfamiliar area:
+
+- Check module boundaries and dependency fan-in in the graph.
+- Note circular dependencies, god modules, and untested high-centrality nodes.
+
+## When to update the graph
+
+Run `graphify update .` after modifying code files in a session (AST-only, no API
+cost). Compare `GRAPH_REPORT.md` commit hash with `git rev-parse HEAD` to detect
+staleness.
+
+## CLI prerequisite
+
+Graphify is not bundled with Kairo Runtime. Install the `graphify` CLI separately
+when you want local graph generation. Kairo only ships the contract and health
+checks.
+
+## Graph signals to watch
+
+| Signal | Risk | Action |
+|---|---|---|
+| Circular dependencies | Hidden coupling | Report and propose cycle break |
+| High fan-in ("god module") | Risky change surface | Evaluate split or narrower API |
+| Orphan module | Dead code or stale docs | Confirm before deleting |
+| High centrality, no tests | Silent regression | Prioritize coverage before edits |
+| Spec without code | Pending or abandoned work | Verify with human |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/scripts/install.sh

@@ -43,8 +43,9 @@ usage() {
     "" \
     "What it does:" \
     "  1. Checks for Node.js and npm." \
-    "  2. Runs the package via npx (or npm exec) with setup --dry-run (default) or setup --yes (--yes)." \
-    "  3. Prints next steps." \
+    "  2. Installs ${PACKAGE} globally (adds kairo to npm global bin)." \
+    "  3. Runs kairo setup --dry-run (default) or kairo setup --yes (--yes)." \
+    "  4. Prints next steps." \
     "" \
     "Security:" \
     "  - Never uses sudo." \
@@ -62,6 +63,51 @@ append_setup_arg() {
   SETUP_EXTRA="${SETUP_EXTRA}${SETUP_EXTRA:+ }$1"
 }
 
+resolve_global_spec() {
+  if [ "$VERSION" = "latest" ]; then
+    printf '%s@latest' "$PACKAGE"
+  else
+    printf '%s@%s' "$PACKAGE" "$VERSION"
+  fi
+}
+
+resolve_npm_global_bin() {
+  npm_prefix="$(npm prefix -g 2>/dev/null || true)"
+  [ -n "$npm_prefix" ] || return 1
+  printf '%s/bin' "$(printf '%s' "$npm_prefix" | sed 's#/*$##')"
+}
+
+resolve_kairo_bin() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    command -v "$PREFERRED_CLI"
+    return 0
+  fi
+
+  global_bin="$(resolve_npm_global_bin || true)"
+  if [ -n "$global_bin" ] && [ -x "${global_bin}/${PREFERRED_CLI}" ]; then
+    printf '%s\n' "${global_bin}/${PREFERRED_CLI}"
+    return 0
+  fi
+
+  return 1
+}
+
+print_path_hint_if_needed() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  global_bin="$(resolve_npm_global_bin || true)"
+  if [ -n "$global_bin" ]; then
+    printf '%s\n' \
+      "" \
+      "PATH note:" \
+      "  ${PREFERRED_CLI} was installed to ${global_bin}." \
+      "  Add it to PATH if the command is not found:" \
+      "    export PATH=\"${global_bin}:\$PATH\""
+  fi
+}
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --dry-run)
@@ -137,14 +183,9 @@ require_cmd npm
 
 NODE_VERSION="$(node --version 2>/dev/null || true)"
 NPM_VERSION="$(npm --version 2>/dev/null || true)"
-
-if command -v npx >/dev/null 2>&1; then
-  RUNNER="npx"
-  RUN_CMD="npx --yes ${PACKAGE}@${VERSION} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
-else
-  RUNNER="npm-exec"
-  RUN_CMD="npm exec --yes --package=${PACKAGE}@${VERSION} -- ${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
-fi
+GLOBAL_SPEC="$(resolve_global_spec)"
+GLOBAL_INSTALL_CMD="npm install -g ${GLOBAL_SPEC}"
+SETUP_CMD="${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
 
 printf '%s\n' \
   "Kairo Runtime bootstrap installer" \
@@ -153,13 +194,13 @@ printf '%s\n' \
   "Prerequisites:" \
   "  node  ${NODE_VERSION:-unknown}" \
   "  npm   ${NPM_VERSION:-unknown}" \
-  "  runner ${RUNNER}" \
   "" \
   "Will run:" \
-  "  ${RUN_CMD}" \
+  "  ${GLOBAL_INSTALL_CMD}" \
+  "  ${SETUP_CMD}" \
   "" \
   "Effects:" \
-  "  - Downloads/runs ${PACKAGE}@${VERSION} via npm (no global install required)." \
+  "  - Installs ${GLOBAL_SPEC} globally (kairo CLI in npm global bin)." \
   "  - Configures managed sections only (never installs AI apps)." \
   "  - Never uses sudo or modifies shell profiles." \
   ""
@@ -181,19 +222,25 @@ if [ "$INSTALLER_DRY_RUN" -eq 1 ]; then
   exit 0
 fi
 
+printf '%s\n' "Installing global CLI..." ""
+# shellcheck disable=SC2086
+npm install -g ${GLOBAL_SPEC}
+
+KAIRO_BIN="$(resolve_kairo_bin || true)"
+if [ -z "$KAIRO_BIN" ]; then
+  die "Installed ${GLOBAL_SPEC}, but ${PREFERRED_CLI} is not available.
+Check npm global bin: $(resolve_npm_global_bin || echo unknown)
+Add it to PATH, then re-run: ${SETUP_CMD}"
+fi
+
 if [ "$APPLY" -eq 1 ]; then
   printf '%s\n' "Applying setup..." ""
 else
   printf '%s\n' "Running preview..." ""
 fi
 
-if [ "$RUNNER" = "npx" ]; then
-  # shellcheck disable=SC2086
-  npx --yes "${PACKAGE}@${VERSION}" setup ${SETUP_MODE} ${SETUP_EXTRA}
-else
-  # shellcheck disable=SC2086
-  npm exec --yes --package="${PACKAGE}@${VERSION}" -- ${PREFERRED_CLI} setup ${SETUP_MODE} ${SETUP_EXTRA}
-fi
+# shellcheck disable=SC2086
+"$KAIRO_BIN" setup ${SETUP_MODE} ${SETUP_EXTRA}
 
 if [ "$APPLY" -eq 1 ]; then
   printf '%s\n' \
@@ -202,24 +249,25 @@ if [ "$APPLY" -eq 1 ]; then
     "Next steps:" \
     "  1. Check health:    ${PREFERRED_CLI} status" \
     "  2. Repair drift:    ${PREFERRED_CLI} sync" \
-    "  3. Upgrade latest:  npx ${PACKAGE}@latest setup --yes" \
+    "  3. Upgrade latest:  ${PREFERRED_CLI} upgrade --dry-run" \
     "" \
     "Version:" \
-    "  Installed CLI:      npx ${PACKAGE} --version" \
-    "  Published package:  npm view ${PACKAGE} version" \
-    "  Preview upgrade:    ${PREFERRED_CLI} upgrade --dry-run"
+    "  Installed CLI:      ${PREFERRED_CLI} --version" \
+    "  Published package:  npm view ${PACKAGE} version"
+  print_path_hint_if_needed
 else
   printf '%s\n' \
     "" \
     "Bootstrap complete." \
     "Next steps:" \
-    "  1. Apply the plan:  npx ${PACKAGE}@${VERSION} setup --yes" \
+    "  1. Apply the plan:  ${PREFERRED_CLI} setup --yes" \
     "     (or re-run installer: curl ... | sh -s -- --yes)" \
-    "  2. Check health:    npx ${PACKAGE}@${VERSION} status" \
-    "  3. Repair drift:    npx ${PACKAGE}@${VERSION} sync" \
+    "  2. Check health:    ${PREFERRED_CLI} status" \
+    "  3. Repair drift:    ${PREFERRED_CLI} sync" \
     "" \
     "Version:" \
-    "  Installed CLI:      npx ${PACKAGE} --version" \
+    "  Installed CLI:      ${PREFERRED_CLI} --version" \
     "  Published package:  npm view ${PACKAGE} version" \
-    "  Update / converge:  npx ${PACKAGE}@latest sync"
+    "  Update / converge:  ${PREFERRED_CLI} sync"
+  print_path_hint_if_needed
 fi

package/scripts/installer-smoke-test.sh

@@ -4,7 +4,9 @@ set -euo pipefail
 PACKAGE="@kal-elsam/kairo-runtime"
 PREFERRED_CLI="kairo"
 VERSION="latest"
+GIT_TAG=""
 REPO="Kal-elSam/harness"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -24,6 +26,14 @@ while [ "$#" -gt 0 ]; do
       VERSION="${1#*=}"
       shift
       ;;
+    --tag)
+      GIT_TAG="$2"
+      shift 2
+      ;;
+    --tag=*)
+      GIT_TAG="${1#*=}"
+      shift
+      ;;
     *)
       echo "Unknown option: $1" >&2
       exit 1
@@ -53,12 +63,13 @@ assert_harness_home_isolated() {
 }
 
 resolve_install_script_url() {
-  if [ "$VERSION" = "latest" ]; then
-    printf '%s\n' "https://raw.githubusercontent.com/${REPO}/main/scripts/install.sh"
-    return
+  local args=(--version "$VERSION" --repo "$REPO")
+
+  if [ -n "$GIT_TAG" ]; then
+    args+=(--tag "$GIT_TAG")
   fi
 
-  printf '%s\n' "https://raw.githubusercontent.com/${REPO}/v${VERSION}/scripts/install.sh"
+  node "${SCRIPT_DIR}/lib/install-script-url.mjs" "${args[@]}"
 }
 
 assert_no_harness_state() {
@@ -117,6 +128,9 @@ cd "$WORKDIR"
 
 INSTALL_SCRIPT_URL="$(resolve_install_script_url)"
 echo "Installer smoke for ${PACKAGE}@${VERSION}"
+if [ -n "$GIT_TAG" ]; then
+  echo "Git tag: ${GIT_TAG}"
+fi
 echo "Install script: ${INSTALL_SCRIPT_URL}"
 echo "Harness home: ${HARNESS_HOME}"
 
@@ -140,15 +154,36 @@ if [ ! -d "$FAKE_HOME/.harness" ]; then
   exit 1
 fi
 
+NPM_GLOBAL_BIN="$(npm prefix -g 2>/dev/null)/bin"
+export PATH="${NPM_GLOBAL_BIN}:${PATH}"
+
+resolve_kairo_bin() {
+  if command -v "$PREFERRED_CLI" >/dev/null 2>&1; then
+    command -v "$PREFERRED_CLI"
+    return 0
+  fi
+  if [ -x "${NPM_GLOBAL_BIN}/${PREFERRED_CLI}" ]; then
+    printf '%s\n' "${NPM_GLOBAL_BIN}/${PREFERRED_CLI}"
+    return 0
+  fi
+  return 1
+}
+
+KAIRO_BIN="$(resolve_kairo_bin || true)"
+if [ -z "$KAIRO_BIN" ]; then
+  echo "Expected ${PREFERRED_CLI} after install.sh global install" >&2
+  exit 1
+fi
+
 echo
 echo "== ${PREFERRED_CLI} status --json =="
-STATUS_JSON="$(npx --yes "${PACKAGE}@${VERSION}" status --json)"
+STATUS_JSON="$("$KAIRO_BIN" status --json)"
 echo "$STATUS_JSON"
 assert_status_ok "$STATUS_JSON"
 
 echo
 echo "== ${PREFERRED_CLI} uninstall =="
-npx --yes "${PACKAGE}@${VERSION}" uninstall
+"$KAIRO_BIN" uninstall
 assert_managed_configs_removed
 
 echo

package/scripts/lib/install-script-url.mjs

@@ -0,0 +1,85 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const DEFAULT_REPO = "Kal-elSam/harness";
+
+export function resolveInstallScriptRef({ version, tag = null }) {
+  if (version === "latest") {
+    return "main";
+  }
+
+  if (tag) {
+    return tag;
+  }
+
+  return `v${version}`;
+}
+
+export function resolveInstallScriptUrl({
+  repo = DEFAULT_REPO,
+  version,
+  tag = null
+}) {
+  const ref = resolveInstallScriptRef({ version, tag });
+  return `https://raw.githubusercontent.com/${repo}/${ref}/scripts/install.sh`;
+}
+
+export function parseInstallScriptUrlArgs(argv) {
+  const args = [...argv];
+  let version = "latest";
+  let tag = null;
+  let repo = DEFAULT_REPO;
+
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--version") {
+      version = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--version=")) {
+      version = arg.slice("--version=".length);
+      continue;
+    }
+
+    if (arg === "--tag") {
+      tag = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--tag=")) {
+      tag = arg.slice("--tag=".length);
+      continue;
+    }
+
+    if (arg === "--repo") {
+      repo = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--repo=")) {
+      repo = arg.slice("--repo=".length);
+      continue;
+    }
+
+    throw new Error(`Unknown option "${arg}".`);
+  }
+
+  return { version, tag, repo };
+}
+
+function isMainModule() {
+  const entry = process.argv[1];
+
+  if (!entry) {
+    return false;
+  }
+
+  return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(entry);
+}
+
+if (isMainModule()) {
+  const { version, tag, repo } = parseInstallScriptUrlArgs(process.argv);
+  console.log(resolveInstallScriptUrl({ repo, version, tag }));
+}

package/src/cli.js

@@ -31,51 +31,21 @@ import { applyPolicyToOptions, loadPolicyFile } from "./global/policy.js";
 import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
 import {
-  ALL_CLI_NAMES,
   LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
   PREFERRED_CLI,
   formatCliCommand,
-  maybeWarnLegacyCli
+  maybeWarnLegacyCli,
+  resolveSuggestedInvocation
 } from "./global/brand/cli.js";
 import { BRAND } from "./global/brand/index.js";
 
+export { resolveSuggestedInvocation };
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const SCOPES = new Set(["agent-global", "workspace"]);
 
-export function resolveSuggestedInvocation(packageName, argv = process.argv) {
-  const invokedPath = argv[1] ?? PREFERRED_CLI;
-  const invokedBase = basename(invokedPath);
-
-  if (!invokedBase.endsWith(".js") && ALL_CLI_NAMES.has(invokedBase)) {
-    return invokedBase;
-  }
-
-  const packageManager = detectInvocationPackageManager();
-
-  switch (packageManager) {
-    case "pnpm":
-      return `pnpm dlx ${packageName}`;
-    case "yarn":
-      return `yarn dlx ${packageName}`;
-    case "bun":
-      return `bunx ${packageName}`;
-    default:
-      return `npx ${packageName}`;
-  }
-}
-
-function detectInvocationPackageManager() {
-  const execPath = process.env.npm_execpath ?? "";
-  const userAgent = process.env.npm_config_user_agent ?? "";
-
-  if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
-  if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
-  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
-  return "npm";
-}
-
 export async function runCli(argv) {
   const { command, options } = parseArgs(argv);
   maybeWarnLegacyCli(process.argv, { json: options.json });

package/src/global/brand/cli.js

@@ -50,3 +50,44 @@ export function formatCliCommand(subcommand, cliName = PREFERRED_CLI) {
   const trimmed = subcommand.trim();
   return trimmed ? `${cliName} ${trimmed}` : cliName;
 }
+
+function detectInvocationPackageManager() {
+  const execPath = process.env.npm_execpath ?? "";
+  const userAgent = process.env.npm_config_user_agent ?? "";
+
+  if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
+  if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
+  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
+  return "npm";
+}
+
+export function resolveSuggestedInvocation(packageName = PACKAGE_NAME, argv = process.argv) {
+  const invokedPath = argv[1] ?? PREFERRED_CLI;
+  const invokedBase = basename(invokedPath);
+
+  if (!invokedBase.endsWith(".js") && ALL_CLI_NAMES.has(invokedBase)) {
+    return invokedBase;
+  }
+
+  const packageManager = detectInvocationPackageManager();
+
+  switch (packageManager) {
+    case "pnpm":
+      return `pnpm dlx ${packageName}`;
+    case "yarn":
+      return `yarn dlx ${packageName}`;
+    case "bun":
+      return `bunx ${packageName}`;
+    default:
+      return `npx ${packageName}`;
+  }
+}
+
+export function formatSuggestedCliCommand(
+  subcommand,
+  { packageName = PACKAGE_NAME, argv = process.argv, suggestedInvocation } = {}
+) {
+  const invoke = suggestedInvocation ?? resolveSuggestedInvocation(packageName, argv);
+  const trimmed = subcommand.trim();
+  return trimmed ? `${invoke} ${trimmed}` : invoke;
+}

package/src/global/brand/index.js

@@ -82,4 +82,10 @@ export function commandHeader(label) {
   return `${BRAND.displayName} ${label}`;
 }
 
-export { formatCliCommand, PREFERRED_CLI } from "./cli.js";
+export {
+  formatCliCommand,
+  formatSuggestedCliCommand,
+  PACKAGE_NAME,
+  PREFERRED_CLI,
+  resolveSuggestedInvocation
+} from "./cli.js";

package/src/global/component-builders.js

@@ -1,10 +1,14 @@
 import { join } from "node:path";
+import { buildEngramMemoryManagedSection } from "./components/engram-memory.js";
+import { buildGraphifyContextManagedSection } from "./components/graphify-context.js";
 import { buildOrchestratorManagedSection } from "./components/orchestrator.js";
 import { buildSddCoreManagedSection } from "./components/sdd-core.js";
 
 export const COMPONENT_BUILDERS = {
   orchestrator: buildOrchestratorManagedSection,
-  "sdd-core": buildSddCoreManagedSection
+  "sdd-core": buildSddCoreManagedSection,
+  "engram-memory": buildEngramMemoryManagedSection,
+  "graphify-context": buildGraphifyContextManagedSection
 };
 
 export function resolveComponentBuilder(componentId) {

package/src/global/component-ecosystem-checks.js

@@ -0,0 +1,147 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { formatCliCommand } from "./brand/cli.js";
+
+const GRAPH_REPORT_COMMIT_PATTERN = /Built from commit:\s*`([0-9a-f]+)`/i;
+
+export async function runComponentEcosystemChecks({ installedComponents, workspaceRoot = null } = {}) {
+  const installedIds = new Set(installedComponents.map((component) => component.id));
+  const checks = [];
+
+  if (installedIds.has("engram-memory")) {
+    checks.push(buildEngramMcpCheck());
+  }
+
+  if (installedIds.has("graphify-context")) {
+    checks.push(...await buildGraphifyChecks(workspaceRoot));
+  }
+
+  return checks;
+}
+
+function buildEngramMcpCheck() {
+  return {
+    name: "engram:mcp-tools",
+    status: "warning",
+    category: "integration",
+    componentId: "engram-memory",
+    detail: "Engram MCP is not bundled. Configure mem_* tools in your agent (user-engram or plugin-engram-engram) when ready."
+  };
+}
+
+async function buildGraphifyChecks(workspaceRoot) {
+  const checks = [];
+
+  if (!workspaceRoot) {
+    checks.push({
+      name: "graphify:workspace",
+      status: "warning",
+      category: "integration",
+      componentId: "graphify-context",
+      detail: "No workspace root; graph freshness checks skipped. Run doctor from a repo cwd."
+    });
+    return checks;
+  }
+
+  const resolvedRoot = resolve(workspaceRoot);
+  const graphifyAvailable = isCommandAvailable("graphify");
+
+  checks.push({
+    name: "graphify:cli",
+    status: graphifyAvailable ? "ok" : "warning",
+    category: "integration",
+    componentId: "graphify-context",
+    detail: graphifyAvailable
+      ? "graphify CLI found in PATH."
+      : "graphify CLI not found in PATH. Install separately when you want local graph generation."
+  });
+
+  const graphPath = join(resolvedRoot, "graphify-out", "graph.json");
+  const reportPath = join(resolvedRoot, "graphify-out", "GRAPH_REPORT.md");
+
+  if (!existsSync(graphPath)) {
+    checks.push({
+      name: "graphify:graph.json",
+      status: "warning",
+      category: "integration",
+      componentId: "graphify-context",
+      detail: existsSync(join(resolvedRoot, "graphify-out"))
+        ? "graphify-out/graph.json is absent. Run `graphify update .` when the workspace is ready."
+        : "graphify-out/ not found. Run `graphify update .` when the workspace is ready."
+    });
+    return checks;
+  }
+
+  const freshness = await readGraphFreshness(resolvedRoot, reportPath);
+  checks.push({
+    name: "graphify:graph.json",
+    status: freshness.status,
+    category: "integration",
+    componentId: "graphify-context",
+    detail: freshness.detail
+  });
+
+  return checks;
+}
+
+async function readGraphFreshness(workspaceRoot, reportPath) {
+  if (!existsSync(reportPath)) {
+    return {
+      status: "warning",
+      detail: "graphify-out/graph.json exists but GRAPH_REPORT.md is missing. Run `graphify update .` to refresh metadata."
+    };
+  }
+
+  const report = await readFile(reportPath, "utf8");
+  const match = report.match(GRAPH_REPORT_COMMIT_PATTERN);
+
+  if (!match) {
+    return {
+      status: "ok",
+      detail: "graphify-out/graph.json present. Commit metadata unavailable in GRAPH_REPORT.md."
+    };
+  }
+
+  const graphCommit = match[1];
+  const headCommit = resolveGitHead(workspaceRoot);
+
+  if (!headCommit) {
+    return {
+      status: "warning",
+      detail: `graphify-out/graph.json present (built from ${graphCommit}). Git HEAD unavailable for staleness check.`
+    };
+  }
+
+  const isFresh = headCommit.startsWith(graphCommit) || graphCommit.startsWith(headCommit);
+
+  if (isFresh) {
+    return {
+      status: "ok",
+      detail: `graphify-out/graph.json in sync with HEAD (${headCommit.slice(0, 8)}).`
+    };
+  }
+
+  return {
+    status: "warning",
+    detail: `graphify-out/graph.json may be stale (graph ${graphCommit}, HEAD ${headCommit.slice(0, 8)}). Run \`graphify update .\` or ${formatCliCommand("sync")} for managed assets only.`
+  };
+}
+
+function resolveGitHead(workspaceRoot) {
+  const result = spawnSync("git", ["rev-parse", "HEAD"], {
+    cwd: workspaceRoot,
+    encoding: "utf8"
+  });
+
+  if (result.status !== 0) return null;
+
+  const head = result.stdout.trim();
+  return head.length > 0 ? head : null;
+}
+
+function isCommandAvailable(command) {
+  const result = spawnSync("which", [command], { encoding: "utf8" });
+  return result.status === 0 && result.stdout.trim().length > 0;
+}

package/src/global/components/engram-memory.js

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+
+export function buildEngramMemoryManagedSection(context, adapter, catalogEntry) {
+  const contractPath = join(context.componentsDir, "engram-memory", "memory.md");
+  const adapterNote = catalogEntry?.adapterHints?.[adapter.id] ?? null;
+
+  return [
+    "### Engram Memory",
+    "",
+    `- Contract: ${contractPath}`,
+    "- Optional persistent memory; repo AGENTS.md and docs/ai/ govern when present.",
+    "- Search memory before non-trivial tasks; save decisions, bugs, and conventions proactively.",
+    "- Authority: user > AGENTS.md > repo docs > Engram > Graphify.",
+    adapterNote
+  ].filter(Boolean).join("\n");
+}

package/src/global/components/graphify-context.js

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+
+export function buildGraphifyContextManagedSection(context, adapter, catalogEntry) {
+  const contractPath = join(context.componentsDir, "graphify-context", "context-graph.md");
+  const adapterNote = catalogEntry?.adapterHints?.[adapter.id] ?? null;
+
+  return [
+    "### Graphify Context",
+    "",
+    `- Contract: ${contractPath}`,
+    "- Optional architecture graph; read GRAPH_REPORT.md before cross-module questions.",
+    "- Run `graphify update .` after code changes when the CLI is available.",
+    "- Authority: user > AGENTS.md > repo docs > Engram > Graphify.",
+    adapterNote
+  ].filter(Boolean).join("\n");
+}

package/src/global/global-doctor.js

@@ -1,5 +1,6 @@
 import { listBackupSnapshots } from "./backups.js";
 import { buildAdapterContext } from "./adapter-context.js";
+import { runComponentEcosystemChecks } from "./component-ecosystem-checks.js";
 import { detectGlobalDrift, hasRepairableDrift } from "./drift.js";
 import { harnessHomePaths } from "./paths.js";
 import { resolveComponent } from "./component-registry.js";
@@ -23,6 +24,10 @@ export async function runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoo
 
   if (packageRoot) {
     checks.push(await backupsCheck(paths));
+    checks.push(...await runComponentEcosystemChecks({
+      installedComponents,
+      workspaceRoot
+    }));
   }
 
   const hasMissing = checks.some((check) => check.status === "missing");

package/src/global/ink/setup-state.js

@@ -1,4 +1,4 @@
-import { AGENT_HINTS, BRAND, PREFERRED_CLI, formatCliCommand, getAgentLabel, WIZARD_COPY } from "../brand/index.js";
+import { AGENT_HINTS, BRAND, formatCliCommand, getAgentLabel, PREFERRED_CLI, WIZARD_COPY } from "../brand/index.js";
 import { formatAgentMultiselectHint } from "../clack/theme.js";
 
 export const SETUP_STEPS = {