@kal-elsam/kairo-runtime 0.11.0 → 0.13.0

package/global-template/components/agent-skills/skills/source-driven-development/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: source-driven-development
+description: Grounds every implementation decision in official documentation. Use when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters.
+---
+
+# Source-Driven Development
+
+## Overview
+
+Every framework-specific code decision must be backed by official documentation. Don't implement from memory — verify, cite, and let the user see your sources. Training data goes stale, APIs get deprecated, best practices evolve. This skill ensures the user gets code they can trust because every pattern traces back to an authoritative source they can check.
+
+## When to Use
+
+- The user wants code that follows current best practices for a given framework
+- Building boilerplate, starter code, or patterns that will be copied across a project
+- The user explicitly asks for documented, verified, or "correct" implementation
+- Implementing features where the framework's recommended approach matters (forms, routing, data fetching, state management, auth)
+- Reviewing or improving code that uses framework-specific patterns
+- Any time you are about to write framework-specific code from memory
+
+**When NOT to use:**
+
+- Correctness does not depend on a specific version (renaming variables, fixing typos, moving files)
+- Pure logic that works the same across all versions (loops, conditionals, data structures)
+- The user explicitly wants speed over verification ("just do it quickly")
+
+## The Process
+
+```
+DETECT ──→ FETCH ──→ IMPLEMENT ──→ CITE
+  │          │           │            │
+  ▼          ▼           ▼            ▼
+ What       Get the    Follow the   Show your
+ stack?     relevant   documented   sources
+            docs       patterns
+```
+
+### Step 1: Detect Stack and Versions
+
+Read the project's dependency file to identify exact versions:
+
+```
+package.json    → Node/React/Vue/Angular/Svelte
+composer.json   → PHP/Symfony/Laravel
+requirements.txt / pyproject.toml → Python/Django/Flask
+go.mod          → Go
+Cargo.toml      → Rust
+Gemfile         → Ruby/Rails
+```
+
+State what you found explicitly:
+
+```
+STACK DETECTED:
+- React 19.1.0 (from package.json)
+- Vite 6.2.0
+- Tailwind CSS 4.0.3
+→ Fetching official docs for the relevant patterns.
+```
+
+If versions are missing or ambiguous, **ask the user**. Don't guess — the version determines which patterns are correct.
+
+### Step 2: Fetch Official Documentation
+
+Fetch the specific documentation page for the feature you're implementing. Not the homepage, not the full docs — the relevant page.
+
+**Source hierarchy (in order of authority):**
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 | Official documentation | react.dev, docs.djangoproject.com, symfony.com/doc |
+| 2 | Official blog / changelog | react.dev/blog, nextjs.org/blog |
+| 3 | Web standards references | MDN, web.dev, html.spec.whatwg.org |
+| 4 | Browser/runtime compatibility | caniuse.com, node.green |
+
+**Not authoritative — never cite as primary sources:**
+
+- Stack Overflow answers
+- Blog posts or tutorials (even popular ones)
+- AI-generated documentation or summaries
+- Your own training data (that is the whole point — verify it)
+
+**Be precise with what you fetch:**
+
+```
+BAD:  Fetch the React homepage
+GOOD: Fetch react.dev/reference/react/useActionState
+
+BAD:  Search "django authentication best practices"
+GOOD: Fetch docs.djangoproject.com/en/6.0/topics/auth/
+```
+
+After fetching, extract the key patterns and note any deprecation warnings or migration guidance.
+
+When official sources conflict with each other (e.g. a migration guide contradicts the API reference), surface the discrepancy to the user and verify which pattern actually works against the detected version.
+
+### Step 3: Implement Following Documented Patterns
+
+Write code that matches what the documentation shows:
+
+- Use the API signatures from the docs, not from memory
+- If the docs show a new way to do something, use the new way
+- If the docs deprecate a pattern, don't use the deprecated version
+- If the docs don't cover something, flag it as unverified
+
+**When docs conflict with existing project code:**
+
+```
+CONFLICT DETECTED:
+The existing codebase uses useState for form loading state,
+but React 19 docs recommend useActionState for this pattern.
+(Source: react.dev/reference/react/useActionState)
+
+Options:
+A) Use the modern pattern (useActionState) — consistent with current docs
+B) Match existing code (useState) — consistent with codebase
+→ Which approach do you prefer?
+```
+
+Surface the conflict. Don't silently pick one.
+
+### Step 4: Cite Your Sources
+
+Every framework-specific pattern gets a citation. The user must be able to verify every decision.
+
+**In code comments:**
+
+```typescript
+// React 19 form handling with useActionState
+// Source: https://react.dev/reference/react/useActionState#usage
+const [state, formAction, isPending] = useActionState(submitOrder, initialState);
+```
+
+**In conversation:**
+
+```
+I'm using useActionState instead of manual useState for the
+form submission state. React 19 replaced the manual
+isPending/setIsPending pattern with this hook.
+
+Source: https://react.dev/blog/2024/12/05/react-19#actions
+"useTransition now supports async functions [...] to handle
+pending states automatically"
+```
+
+**Citation rules:**
+
+- Full URLs, not shortened
+- Prefer deep links with anchors where possible (e.g. `/useActionState#usage` over `/useActionState`) — anchors survive doc restructuring better than top-level pages
+- Quote the relevant passage when it supports a non-obvious decision
+- Include browser/runtime support data when recommending platform features
+- If you cannot find documentation for a pattern, say so explicitly:
+
+```
+UNVERIFIED: I could not find official documentation for this
+pattern. This is based on training data and may be outdated.
+Verify before using in production.
+```
+
+Honesty about what you couldn't verify is more valuable than false confidence.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'm confident about this API" | Confidence is not evidence. Training data contains outdated patterns that look correct but break against current versions. Verify. |
+| "Fetching docs wastes tokens" | Hallucinating an API wastes more. The user debugs for an hour, then discovers the function signature changed. One fetch prevents hours of rework. |
+| "The docs won't have what I need" | If the docs don't cover it, that's valuable information — the pattern may not be officially recommended. |
+| "I'll just mention it might be outdated" | A disclaimer doesn't help. Either verify and cite, or clearly flag it as unverified. Hedging is the worst option. |
+| "This is a simple task, no need to check" | Simple tasks with wrong patterns become templates. The user copies your deprecated form handler into ten components before discovering the modern approach exists. |
+
+## Red Flags
+
+- Writing framework-specific code without checking the docs for that version
+- Using "I believe" or "I think" about an API instead of citing the source
+- Implementing a pattern without knowing which version it applies to
+- Citing Stack Overflow or blog posts instead of official documentation
+- Using deprecated APIs because they appear in training data
+- Not reading `package.json` / dependency files before implementing
+- Delivering code without source citations for framework-specific decisions
+- Fetching an entire docs site when only one page is relevant
+
+## Verification
+
+After implementing with source-driven development:
+
+- [ ] Framework and library versions were identified from the dependency file
+- [ ] Official documentation was fetched for framework-specific patterns
+- [ ] All sources are official documentation, not blog posts or training data
+- [ ] Code follows the patterns shown in the current version's documentation
+- [ ] Non-trivial decisions include source citations with full URLs
+- [ ] No deprecated APIs are used (checked against migration guides)
+- [ ] Conflicts between docs and existing code were surfaced to the user
+- [ ] Anything that could not be verified is explicitly flagged as unverified

package/global-template/components/catalog.json

@@ -108,6 +108,35 @@
         "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."
       }
+    },
+    {
+      "id": "agent-skills",
+      "kind": "component",
+      "label": "Agent Skills (complementary)",
+      "version": "1.0.0",
+      "defaultEnabled": false,
+      "capabilities": ["skills.complementary"],
+      "dependencies": [],
+      "healthChecks": [
+        { "id": "assets", "type": "assets" },
+        { "id": "drift", "type": "drift" }
+      ],
+      "assetFiles": [
+        "LICENSE",
+        "PROVENANCE.md",
+        "skills/context-engineering/SKILL.md",
+        "skills/source-driven-development/SKILL.md",
+        "skills/frontend-ui-engineering/SKILL.md",
+        "skills/performance-optimization/SKILL.md",
+        "skills/observability-and-instrumentation/SKILL.md"
+      ],
+      "adapterHints": {
+        "cursor": "- Complementary only; Gentle AI remains methodological authority. After install, run `gentle-ai skill-registry refresh` when available.",
+        "codex": "- Complementary only; Gentle AI remains methodological authority. After install, run `gentle-ai skill-registry refresh` when available.",
+        "claude": "- Complementary only; Gentle AI remains methodological authority. After install, run `gentle-ai skill-registry refresh` when available.",
+        "opencode": "- Complementary only; Gentle AI remains methodological authority. After install, run `gentle-ai skill-registry refresh` when available.",
+        "pi": "- Complementary only; Gentle AI remains methodological authority. Skills load from the shared Agent Skills root when linked; do not replace Gentle AI SDD/review gates."
+      }
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",
@@ -30,6 +30,7 @@
   ],
   "scripts": {
     "test": "node --test",
+    "test:cool": "node --test --test-concurrency=1",
     "doctor": "node ./bin/kairo.js doctor",
     "smoke": "bash scripts/smoke-test.sh",
     "ux:smoke": "bash scripts/ux-smoke-test.sh",
@@ -61,8 +62,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "ansi-escapes": "^7.3.0",
     "ink": "^5.2.1",
-    "react": "^18.3.1"
+    "react": "^18.3.1",
+    "zod": "4.4.3"
   }
 }

package/scripts/cockpit-smoke.mjs

@@ -26,7 +26,8 @@ const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const require = createRequire(import.meta.url);
 const pkg = require(join(root, "package.json"));
 
-assert.equal(pkg.version, "0.11.0");
+assert.match(pkg.version, /^\d+\.\d+\.\d+$/);
+assert.equal(pkg.name, "@kal-elsam/kairo-runtime");
 assert.ok(pkg.dependencies["ansi-escapes"]);
 
 assert.equal(resolveLayoutMode({ columns: 120, rows: 40 }), LAYOUT_MODES.WIDE);

package/src/cli.js

@@ -32,6 +32,7 @@ import {
   runGlobalHistory,
   runGlobalReport
 } from "./global/global-cli.js";
+import { runEcosystemUpdatesCheck } from "./global/updates-cli.js";
 import { applyPolicyToOptions, loadPolicyFile } from "./global/policy.js";
 import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
@@ -40,6 +41,9 @@ import { runIntelligenceCli } from "./global/intelligence-cli.js";
 import { runGlobalRun, runGlobalRuns } from "./global/runtime/run-cli.js";
 import { runGlobalReview, runGlobalReviews } from "./global/runtime/review/review-cli.js";
 import { runGlobalMonitor } from "./global/runtime/monitor/monitor-cli.js";
+import { runGlobalAlerts } from "./global/runtime/alerts/alert-cli.js";
+import { runGraphifyCli } from "./global/observability/graphify-ops.js";
+import { runKairoMcp } from "./global/mcp/kairo-mcp.js";
 import { normalizeRunStrategy } from "./global/runtime/run-strategy.js";
 import {
   LEGACY_PACKAGE_NAME,
@@ -123,6 +127,21 @@ export async function runCli(argv) {
     case "monitor":
       await runGlobalMonitor(optionsWithPolicy, packageManifest, { packageRoot });
       return;
+    case "alerts":
+      await runGlobalAlerts(optionsWithPolicy);
+      return;
+    case "graphify":
+      await runGraphifyCli(optionsWithPolicy, packageManifest);
+      return;
+    case "mcp":
+      // stdout reserved for MCP protocol — no banners/logs here
+      await runKairoMcp({
+        cwd: optionsWithPolicy.cwd,
+        packageRoot,
+        packageName: packageManifest.name,
+        version: packageManifest.version
+      });
+      return;
     case "intelligence":
       await runIntelligenceCli(optionsWithPolicy, packageManifest);
       return;
@@ -142,6 +161,9 @@ export async function runCli(argv) {
     case "upgrade":
       await runGlobalUpgrade(optionsWithPolicy, packageManifest, packageRoot);
       return;
+    case "updates":
+      await runEcosystemUpdatesCheck(optionsWithPolicy, packageManifest);
+      return;
     case "install":
       await dispatchByScope(options, "agent-global", {
         "agent-global": () => runGlobalInstall(options, packageManifest, packageRoot),
@@ -384,9 +406,18 @@ export function parseArgs(argv) {
     runsAction: null,
     runId: null,
     reviewId: null,
+    lineage: null,
     reviewsAction: null,
+    confirmImport: false,
+    alertsAction: null,
+    alertId: null,
+    confirmResolve: false,
+    confirmDismiss: false,
+    graphifyAction: null, graphifyArgs: [], graphifyBudget: null, graphPath: null,
+    updatesAction: "check",
     base: null,
     commit: null,
+    staged: false,
     failOn: null,
     agent: null,
     task: null,
@@ -394,6 +425,7 @@ export function parseArgs(argv) {
     strategy: "direct",
     intelligenceBackend: null,
     permissions: null,
+    allowUnsafePermissions: false,
     captureTranscript: false,
     follow: false,
     wait: true,
@@ -431,6 +463,13 @@ export function parseArgs(argv) {
     parseMonitorAction(args, options);
   }
 
+  if (command === "alerts") {
+    parseAlertsAction(args, options);
+  }
+
+  if (command === "graphify") parseGraphifyAction(args, options);
+  if (command === "updates") parseUpdatesAction(args, options);
+
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
 
@@ -520,6 +559,16 @@ export function parseArgs(argv) {
     else if (arg.startsWith("--backend=")) options.intelligenceBackend = arg.slice("--backend=".length);
     else if (arg === "--permissions") options.permissions = parsePathList(args[++index]);
     else if (arg.startsWith("--permissions=")) options.permissions = parsePathList(arg.slice("--permissions=".length));
+    else if (arg === "--bundle") options.bundlePath = resolve(args[++index]);
+    else if (arg.startsWith("--bundle=")) options.bundlePath = resolve(arg.slice("--bundle=".length));
+    else if (arg === "--graph") options.graphPath = resolve(args[++index]);
+    else if (arg.startsWith("--graph=")) options.graphPath = resolve(arg.slice("--graph=".length));
+    else if (arg === "--budget") options.graphifyBudget = requireFlagValue("--budget", args[++index]);
+    else if (arg.startsWith("--budget=")) options.graphifyBudget = requireFlagValue("--budget", arg.slice("--budget=".length));
+    else if (arg === "--confirm-import") options.confirmImport = true;
+    else if (arg === "--confirm-resolve") options.confirmResolve = true;
+    else if (arg === "--confirm-dismiss") options.confirmDismiss = true;
+    else if (arg === "--allow-unsafe-permissions") options.allowUnsafePermissions = true;
     else if (arg === "--capture-transcript") options.captureTranscript = true;
     else if (arg === "--follow") options.follow = true;
     else if (arg === "--no-wait") options.wait = false;
@@ -533,7 +582,8 @@ export function parseArgs(argv) {
     else if (arg === "--commit") options.commit = requireFlagValue("--commit", args[++index]);
     else if (arg.startsWith("--commit=")) {
       options.commit = requireFlagValue("--commit", arg.slice("--commit=".length));
-    } else if (arg === "--fail-on") options.failOn = requireFlagValue("--fail-on", args[++index]);
+    } else if (arg === "--staged") options.staged = true;
+    else if (arg === "--fail-on") options.failOn = requireFlagValue("--fail-on", args[++index]);
     else if (arg.startsWith("--fail-on=")) {
       options.failOn = requireFlagValue("--fail-on", arg.slice("--fail-on=".length));
     }
@@ -546,6 +596,16 @@ export function parseArgs(argv) {
     options.task = args.join(" ").trim();
   }
 
+  if (command === "reviews" && options.reviewsAction === "import" && !options.bundlePath) {
+    throw new Error(
+      `Missing --bundle. Use: ${formatCliCommand("reviews import --bundle <path> --confirm-import")}`
+    );
+  }
+
+  if (command === "graphify" && !options.graphPath) {
+    throw new Error(`Missing --graph. Use: ${formatCliCommand("graphify <query|path|explain> ... --graph <path>")}`);
+  }
+
   return { command, options, isImplicitCommand: implicitCommand };
 }
 
@@ -672,18 +732,27 @@ function parseReviewsAction(args, options) {
     options.reviewsAction = "list";
     return;
   }
-  if (!new Set(["list", "show"]).has(action)) {
-    throw new Error(`Unknown reviews action "${action}". Use list or show.`);
+  if (!new Set(["list", "show", "verify", "export", "import"]).has(action)) {
+    throw new Error(`Unknown reviews action "${action}". Use list, show, verify, export, or import.`);
   }
   args.shift();
   options.reviewsAction = action;
-  if (action === "show") {
+  if (action === "show" || action === "verify") {
     const reviewId = args[0];
     if (!reviewId || reviewId.startsWith("-")) {
-      throw new Error(`Missing review id. Use: ${formatCliCommand("reviews show <reviewId>")}`);
+      throw new Error(`Missing review id. Use: ${formatCliCommand(`reviews ${action} <reviewId>`)}`);
     }
     options.reviewId = args.shift();
   }
+  if (action === "export") {
+    const lineage = args[0];
+    if (!lineage || lineage.startsWith("-")) {
+      throw new Error(
+        `Missing lineage. Use: ${formatCliCommand("reviews export <lineage> --out <path>")}`
+      );
+    }
+    options.lineage = args.shift();
+  }
 }
 
 function parseMonitorAction(args, options) {
@@ -699,6 +768,20 @@ function parseMonitorAction(args, options) {
   options.monitorAction = action;
 }
 
+function parseAlertsAction(args, options) {
+  const action = args[0];
+  if (!action || action.startsWith("-") || !new Set(["resolve", "dismiss"]).has(action)) {
+    throw new Error(`Unknown alerts action "${action ?? ""}". Use resolve or dismiss.`);
+  }
+  args.shift();
+  options.alertsAction = action;
+  const alertId = args[0];
+  if (!alertId || alertId.startsWith("-")) {
+    throw new Error(`Missing alert id. Use: ${formatCliCommand(`alerts ${action} <alertId>`)}`);
+  }
+  options.alertId = args.shift();
+}
+
 function parseIntelligenceAction(args, options) {
   const action = args[0];
   if (!action || action.startsWith("-")) {
@@ -714,6 +797,39 @@ function parseIntelligenceAction(args, options) {
   options.intelligenceAction = action;
 }
 
+function parseGraphifyAction(args, options) {
+  const action = args[0];
+  const usage = formatCliCommand("graphify <query|path|explain> ... --graph <path>");
+  if (!action || action.startsWith("-")) throw new Error(`Missing graphify action. Use: ${usage}`);
+  if (!["query", "path", "explain"].includes(action)) {
+    throw new Error(`Unknown graphify action "${action}". Use query, path, or explain.`);
+  }
+  args.shift();
+  options.graphifyAction = action;
+  const positional = [];
+  while (args.length && !String(args[0]).startsWith("-")) positional.push(args.shift());
+  const need = action === "path" ? 2 : 1;
+  if (positional.length < need) {
+    throw new Error(action === "path"
+      ? `Missing arguments. Use: ${formatCliCommand('graphify path "<A>" "<B>" --graph <path>')}`
+      : `Missing argument. Use: ${formatCliCommand(`graphify ${action} "<text>" --graph <path>`)}`);
+  }
+  options.graphifyArgs = positional.slice(0, need);
+}
+
+function parseUpdatesAction(args, options) {
+  const action = args[0];
+  if (!action || action.startsWith("-")) {
+    options.updatesAction = "check";
+    return;
+  }
+  if (action !== "check") {
+    throw new Error(`Unknown updates action "${action}". Use: kairo updates check`);
+  }
+  args.shift();
+  options.updatesAction = "check";
+}
+
 function parsePathList(value) {
   if (!value) return [];
   return [...new Set(
@@ -758,11 +874,15 @@ function normalizeCommand(command) {
   if (command === "review") return "review";
   if (command === "reviews") return "reviews";
   if (command === "monitor") return "monitor";
+  if (command === "alerts") return "alerts";
+  if (command === "graphify") return "graphify";
+  if (command === "mcp") return "mcp";
   if (command === "intelligence" || command === "intel") return "intelligence";
   if (command === "setup") return "setup";
   if (command === "status") return "status";
   if (command === "sync") return "sync";
   if (command === "upgrade") return "upgrade";
+  if (command === "updates") return "updates";
   if (command === "init") return "init";
   if (command === "update" || command === "u") return "update";
   if (command === "doctor") return "doctor";
@@ -828,13 +948,18 @@ Usage:
   ${cli} --dry-run                      Setup dry-run (scriptable)
   ${cli} --version
   ${cli} shell                          Operations cockpit (TTY)
-  ${cli} run --agent <id> --task "..." [--strategy direct|orchestrated] [--model <name>] [--cwd <dir>] [--permissions force] [--capture-transcript] [--follow] [--no-wait] [--json]
+  ${cli} run --agent <id> --task "..." [--strategy direct|orchestrated] [--model <name>] [--cwd <dir>] [--permissions force|yolo|read-only] [--allow-unsafe-permissions] [--capture-transcript] [--follow] [--no-wait] [--json]
   ${cli} runs list [--json] [--limit <n>] [--active-only]
   ${cli} runs show <runId> [--json] [--limit <n>] [--follow]
   ${cli} runs stop <runId> [--json]
-  ${cli} review --agent codex|pi [--base <ref>|--commit <sha>] [--model <name>] [--include-private] [--yes|--confirm] [--fail-on high|medium|low] [--json]
+  ${cli} alerts resolve|dismiss <alertId> --confirm-resolve|--confirm-dismiss [--json]
+  ${cli} review --agent codex|pi [--base <ref>|--commit <sha>|--staged] [--model <name>] [--include-private] [--yes|--confirm] [--fail-on high|medium|low] [--json]
   ${cli} reviews list [--limit <n>] [--json]
   ${cli} reviews show <reviewId> [--json]
+  ${cli} reviews verify <reviewId> --staged [--json]
+  ${cli} reviews export <lineage> --out <path> [--json]
+  ${cli} reviews import --bundle <path> --confirm-import [--cwd <dir>] [--json]
+  ${cli} graphify query|path|explain ... --graph <path> [--budget N] [--json]
   ${cli} orchestrator [--json]          Read-only agent capability diagnostics
   ${cli} intelligence [status|models|context|route|ask] [--json]
   ${cli} intelligence models --backend opencode-go|opencode-zen|opencode
@@ -844,6 +969,7 @@ Usage:
   ${cli} status [--json]
   ${cli} sync [--dry-run] [--yes] [--confirm] [--json] [--no-preflight]
   ${cli} upgrade [--dry-run] [--yes] [--confirm] [--no-preflight]
+  ${cli} updates check [--json] [--force]
   ${cli} install [--agents <list|all>] [--components <list>] [--dry-run]
   ${cli} install --no-default-components
   ${cli} doctor [--json]
@@ -883,8 +1009,9 @@ Commands:
              Tab switches region only when content is interactive (runs/launch).
   run        Launch a managed agent run with local audit trail.
   runs       List, inspect, or cancel agent runs under ~/.harness/runs/.
+  alerts     Consent-gated alert resolve/dismiss (Permission Authority).
   review     Bounded read-only review via Codex or Pi; receipts under ~/.harness/reviews/.
-  reviews    List or show prior review receipts (secret-free).
+  reviews    List/show/verify receipts, or Gentle portable export/import.
   monitor    Opt-in anomaly monitor (enable|disable|status|tick). macOS LaunchAgent; notify shell:false.
   orchestrator  Read-only capability registry diagnostics (--json supported).
   intelligence  Harness Engineering layer: backends, context packs, routing, budgets.
@@ -895,6 +1022,7 @@ Commands:
   status     Control panel: agents, components, drift, backups, next action.
   sync       Converge managed content (repair drift), then show status.
   upgrade    Preview or apply ecosystem updates (apply requires --yes).
+  updates    Read-only ecosystem update check (kairo/hermes/gentle/skills). Never applies.
   install    Non-interactive configure (agent-global) or legacy workspace scaffold.
   doctor     Detailed health checks for managed state and configs.
   update     Technical repair alias (prefer sync for day-to-day use).

package/src/global/component-builders.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { buildAgentSkillsManagedSection } from "./components/agent-skills.js";
 import { buildEngramMemoryManagedSection } from "./components/engram-memory.js";
 import { buildGraphifyContextManagedSection } from "./components/graphify-context.js";
 import { buildOrchestratorManagedSection } from "./components/orchestrator.js";
@@ -8,7 +9,8 @@ export const COMPONENT_BUILDERS = {
   orchestrator: buildOrchestratorManagedSection,
   "sdd-core": buildSddCoreManagedSection,
   "engram-memory": buildEngramMemoryManagedSection,
-  "graphify-context": buildGraphifyContextManagedSection
+  "graphify-context": buildGraphifyContextManagedSection,
+  "agent-skills": buildAgentSkillsManagedSection
 };
 
 export function resolveComponentBuilder(componentId) {

package/src/global/components/agent-skills.js

@@ -0,0 +1,27 @@
+import { join } from "node:path";
+
+export const AGENT_SKILLS_IDS = Object.freeze([
+  "context-engineering",
+  "source-driven-development",
+  "frontend-ui-engineering",
+  "performance-optimization",
+  "observability-and-instrumentation"
+]);
+
+export function buildAgentSkillsManagedSection(context, adapter, catalogEntry) {
+  const baseDir = join(context.componentsDir, "agent-skills");
+  const adapterNote = catalogEntry?.adapterHints?.[adapter.id] ?? null;
+
+  return [
+    "### Agent Skills (complementary)",
+    "",
+    `- Skills root: ${join(baseDir, "skills")}`,
+    `- Provenance: ${join(baseDir, "PROVENANCE.md")}`,
+    `- License: ${join(baseDir, "LICENSE")}`,
+    `- Adopted skills (only): ${AGENT_SKILLS_IDS.join(", ")}.`,
+    "- Complementary only: Gentle AI remains the methodological authority for SDD, RDD, review, and Git workflow.",
+    "- Do not treat these skills as replacements for Gentle AI phase skills or review gates.",
+    "- After install or update, run `gentle-ai skill-registry refresh` when Gentle AI is available.",
+    adapterNote
+  ].filter(Boolean).join("\n");
+}