@fenglimg/fabric-server 2.0.0-rc.34 → 2.0.0-rc.35

package/dist/{chunk-Z23PAA5L.js → chunk-DRIWYXFP.js}

@@ -88,7 +88,7 @@ import { agentsMetaSchema as agentsMetaSchema2 } from "@fenglimg/fabric-shared";
 var AgentsMetaFileMissingError = class extends IOFabricError {
   constructor(metaPath, opts) {
     super(`Fabric agents metadata file is missing: ${metaPath}`, {
-      actionHint: opts?.actionHint ?? "Run `fab install` to scaffold the .fabric/agents.meta.json file"
+      actionHint: opts?.actionHint ?? "Run `fabric install` to scaffold the .fabric/agents.meta.json file"
     });
     this.metaPath = metaPath;
   }
@@ -241,7 +241,7 @@ async function appendEventLedgerEvent(projectRoot, event) {
       if (size > EVENT_LEDGER_SIZE_WARN_BYTES) {
         warnedOversize = true;
         process.stderr.write(
-          'fabric: events.jsonl > 50MB, run "fab doctor --fix" to rotate\n'
+          'fabric: events.jsonl > 50MB, run "fabric doctor --fix" to rotate\n'
         );
       }
     } catch {
@@ -1280,7 +1280,7 @@ function validateFrontmatter(source, filePath, throwOnInvalid) {
     const msg = `Unterminated YAML frontmatter in ${filePath}`;
     if (throwOnInvalid) {
       throw new RuleValidationError(msg, {
-        actionHint: "Run `fab doctor --fix` to repair frontmatter",
+        actionHint: "Run `fabric doctor --fix` to repair frontmatter",
         fixable: true,
         details: { file: filePath }
       });
@@ -1288,7 +1288,7 @@ function validateFrontmatter(source, filePath, throwOnInvalid) {
     return {
       code: "rule_frontmatter_invalid",
       file: filePath,
-      action_hint: "Run `fab doctor --fix` to repair frontmatter"
+      action_hint: "Run `fabric doctor --fix` to repair frontmatter"
     };
   }
   const frontmatter = source.slice(3, endIdx).trim();
@@ -1301,7 +1301,7 @@ function validateFrontmatter(source, filePath, throwOnInvalid) {
       const msg = `Invalid YAML frontmatter line "${trimmed}" in ${filePath}`;
       if (throwOnInvalid) {
         throw new RuleValidationError(msg, {
-          actionHint: "Run `fab doctor --fix` to repair frontmatter",
+          actionHint: "Run `fabric doctor --fix` to repair frontmatter",
           fixable: true,
           details: { file: filePath, line: trimmed }
         });
@@ -1309,7 +1309,7 @@ function validateFrontmatter(source, filePath, throwOnInvalid) {
       return {
         code: "rule_frontmatter_invalid",
         file: filePath,
-        action_hint: "Run `fab doctor --fix` to repair frontmatter"
+        action_hint: "Run `fabric doctor --fix` to repair frontmatter"
       };
     }
   }
@@ -1634,13 +1634,14 @@ function checkLockOrThrow(projectRoot, opts) {
 }
 
 // src/services/doctor.ts
-import { execFileSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import { existsSync as existsSync5, readdirSync, readFileSync as readFileSync3, statSync as statSync4 } from "fs";
 import { access, mkdir as mkdir4, readFile as readFile5, rename, unlink, writeFile as writeFile2 } from "fs/promises";
 import { constants } from "fs";
 import { homedir as homedir3 } from "os";
 import { isAbsolute as isAbsolute2, join as join7, posix, relative as nodeRelative, resolve as resolve3, sep as sep3 } from "path";
 import { minimatch } from "minimatch";
+import { ZodError } from "zod";
 import {
   agentsMetaSchema as agentsMetaSchema4,
   AgentsMetaCountersSchema,
@@ -1857,6 +1858,7 @@ async function runDoctorReport(target) {
   const onboardCoverage = inspectOnboardCoverage(projectRoot);
   const hooksWired = inspectHooksWired(projectRoot);
   const promoteLedgerInvariant = eventLedger.exists && eventLedger.writable && eventLedger.parseable ? await inspectPromoteLedgerInvariant(projectRoot) : null;
+  const globalCliVersion = process.env.VITEST === "true" ? { status: "ok", version: "test-skipped" } : inspectGlobalCliVersion();
   const checks = [
     createBootstrapAnchorCheck(t, bootstrapAnchor),
     // v2.0.0-rc.19 TASK-004: bootstrap marker migration check sits adjacent to
@@ -1880,7 +1882,7 @@ async function runDoctorReport(target) {
     // The file's absence is a legitimate post-init state when the skill has
     // not yet run, so flagging it as a doctor manual_error misrepresents
     // ownership.
-    createMetaCheck(t, meta),
+    createMetaCheck(t, meta, globalCliVersion),
     createRuleContentRefCheck(t, meta),
     // v2.0 / rc.2: `createRuleSectionsCheck` removed — it parsed v1.x
     // [MANDATORY_INJECTION] sections out of legacy rule files, a structural
@@ -1896,7 +1898,7 @@ async function runDoctorReport(target) {
     // v2.0.0-rc.28 TASK-04 (audit §3.1 follow-up): SKILL ref/ mirror parity.
     // Detects hand-edits or partial install that breaks the byte-identical
     // contract between .claude/skills/<slug>/ref/ and .codex/skills/<slug>/
-    // ref/. warning severity — fab install restores parity.
+    // ref/. warning severity — fabric install restores parity.
     createSkillRefMirrorCheck(t, skillRefMirror),
     createSkillTokenBudgetCheck(t, skillTokenBudget),
     createSkillDescriptionCheck(t, skillDescription),
@@ -1958,6 +1960,15 @@ async function runDoctorReport(target) {
     // rc.31 BUG-M3/NEW-4: hooks_wired observability. Adjacent to onboard /
     // promote-ledger checks — all three are install/runtime-state advisories.
     createHooksWiredCheck(t, hooksWired),
+    // rc.35 TASK-04 (P0-9.b): global CLI version probe — surfaces rc.30 PATH
+    // installs against rc.31+ project schemas (the silent-hooks fault mode).
+    // Sits next to hooks_wired since both lints diagnose runtime install state.
+    createGlobalCliVersionCheck(t, globalCliVersion),
+    // rc.35 TASK-05 (P0-10.a): opaque-summary ratio — surfaces the
+    // werewolf-eval failure mode where description.summary == stable_id so
+    // hint output is "KT-PIT-0001 · KT-PIT-0001" (AI skips fetch). Built
+    // from the same MetaInspection so no extra disk reads.
+    createKnowledgeSummaryOpaqueCheck(t, inspectKnowledgeSummaryOpaque(meta)),
     // rc.31 BUG-G2/G5: promote-ledger invariant. Sits adjacent to onboard
     // coverage — both are observability advisories built off events.jsonl.
     ...promoteLedgerInvariant === null ? [] : [createPromoteLedgerInvariantCheck(t, promoteLedgerInvariant)],
@@ -2615,6 +2626,17 @@ async function inspectMeta(projectRoot) {
         changed: built?.changed ?? true
       };
     }
+    let readErrorKind = "other";
+    let readErrorZodIssues;
+    if (error instanceof ZodError) {
+      readErrorKind = "zod";
+      readErrorZodIssues = error.issues.slice(0, 3).map((issue) => ({
+        path: issue.path.length > 0 ? issue.path.join(".") : "<root>",
+        message: issue.message
+      }));
+    } else if (error instanceof SyntaxError) {
+      readErrorKind = "json";
+    }
     return {
       present: true,
       valid: false,
@@ -2622,6 +2644,8 @@ async function inspectMeta(projectRoot) {
       revision: null,
       computedRevision: built?.meta.revision ?? null,
       ruleCount: 0,
+      readErrorKind,
+      readErrorZodIssues,
       missingContentRefs: [],
       invalidContentRefs: [],
       stale: true,
@@ -3325,7 +3349,7 @@ function createForensicCheck(t, forensic, frameworkKind, entryPointCount) {
     t("doctor.check.forensic.ok", { frameworkKind: forensic.report?.framework.kind ?? "unknown" })
   );
 }
-function createMetaCheck(t, meta) {
+function createMetaCheck(t, meta, globalCli) {
   if (!meta.present) {
     return issueCheck(
       t("doctor.check.agents_meta.name"),
@@ -3337,6 +3361,30 @@ function createMetaCheck(t, meta) {
     );
   }
   if (!meta.valid) {
+    if (globalCli && globalCli.status === "outdated") {
+      return issueCheck(
+        t("doctor.check.agents_meta.name"),
+        "error",
+        "manual_error",
+        "agents_meta_invalid_global_cli_outdated",
+        t("doctor.check.agents_meta.message.invalid-from-old-cli", {
+          version: globalCli.version,
+          minVersion: globalCli.minVersion
+        }),
+        t("doctor.check.global_cli_outdated.remediation")
+      );
+    }
+    if (meta.readErrorKind === "zod" && meta.readErrorZodIssues && meta.readErrorZodIssues.length > 0) {
+      const formatted = meta.readErrorZodIssues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+      return issueCheck(
+        t("doctor.check.agents_meta.name"),
+        "error",
+        "manual_error",
+        "agents_meta_invalid",
+        t("doctor.check.agents_meta.message.invalid-zod", { issues: formatted }),
+        t("doctor.check.agents_meta.remediation.invalid")
+      );
+    }
     return issueCheck(
       t("doctor.check.agents_meta.name"),
       "error",
@@ -3569,7 +3617,11 @@ function createSkillTokenBudgetCheck(t, inspection) {
       count: String(count),
       list
     }),
-    t("doctor.check.skill_token_budget.remediation")
+    t("doctor.check.skill_token_budget.remediation"),
+    // rc.35 TASK-12 (P0-11): maintainer audience. Remediation points at
+    // `packages/cli/templates/skills/*` source — only Fabric contributors
+    // can act. CLI renderer folds by default; --verbose unfolds.
+    "maintainer"
   );
 }
 function createDraftBacklogCheck(t, inspection) {
@@ -3611,7 +3663,11 @@ function createCiteGoodhartCheck(t, inspection) {
       count: String(count),
       list
     }),
-    t("doctor.check.cite_goodhart.remediation")
+    t("doctor.check.cite_goodhart.remediation"),
+    // rc.35 TASK-12 (P0-11): maintainer audience. G1/G2/G3/G5 are internal
+    // pattern codes from the cite-policy design memo — npm end users have
+    // no actionable lever for these. Fold by default; --verbose unfolds.
+    "maintainer"
   );
 }
 function createSkillDescriptionCheck(t, inspection) {
@@ -3632,7 +3688,10 @@ function createSkillDescriptionCheck(t, inspection) {
       count: String(count),
       list
     }),
-    t("doctor.check.skill_description.remediation")
+    t("doctor.check.skill_description.remediation"),
+    // rc.35 TASK-12 (P0-11): maintainer audience. Remediation points at
+    // `packages/cli/templates/skills/<slug>/SKILL.md` frontmatter.
+    "maintainer"
   );
 }
 function createEventLedgerPartialWriteCheck(t, ledger) {
@@ -3794,7 +3853,157 @@ function createPromoteLedgerInvariantCheck(t, inspection) {
     t("doctor.check.promote_ledger_invariant.remediation")
   );
 }
-function issueCheck(name, status, kind, code, message, actionHint) {
+var MIN_SUPPORTED_GLOBAL_CLI_VERSION = "2.0.0-rc.31";
+var defaultGlobalCliSpawn = () => {
+  const res = spawnSync("fabric", ["-v"], {
+    encoding: "utf8",
+    timeout: 5e3,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return { error: res.error ?? null, status: res.status, stdout: res.stdout };
+};
+function inspectGlobalCliVersion(spawn = defaultGlobalCliSpawn) {
+  let res;
+  try {
+    res = spawn();
+  } catch (e) {
+    return { status: "unparseable", detail: e instanceof Error ? e.message : String(e) };
+  }
+  if (res.error) {
+    if (res.error.code === "ENOENT") {
+      return { status: "not-found" };
+    }
+    return { status: "unparseable", detail: res.error.message };
+  }
+  if (res.status !== 0) {
+    return { status: "unparseable", detail: `exit ${res.status ?? "?"}` };
+  }
+  const raw = (res.stdout ?? "").trim();
+  const m = /(\d+)\.(\d+)\.(\d+)-rc\.(\d+)/.exec(raw);
+  if (!m) {
+    return { status: "unparseable", detail: raw.slice(0, 80) };
+  }
+  const version = `${m[1]}.${m[2]}.${m[3]}-rc.${m[4]}`;
+  const observedRc = Number(m[4]);
+  const minMatch = /-rc\.(\d+)/.exec(MIN_SUPPORTED_GLOBAL_CLI_VERSION);
+  const minRc = minMatch ? Number(minMatch[1]) : 0;
+  if (observedRc < minRc) {
+    return { status: "outdated", version, minVersion: MIN_SUPPORTED_GLOBAL_CLI_VERSION };
+  }
+  return { status: "ok", version };
+}
+function createGlobalCliVersionCheck(t, inspection) {
+  if (inspection.status === "ok") {
+    return okCheck(
+      t("doctor.check.global_cli_outdated.name"),
+      t("doctor.check.global_cli_outdated.ok", { version: inspection.version })
+    );
+  }
+  if (inspection.status === "outdated") {
+    return issueCheck(
+      t("doctor.check.global_cli_outdated.name"),
+      "error",
+      "manual_error",
+      "global_cli_outdated",
+      t("doctor.check.global_cli_outdated.message.outdated", {
+        version: inspection.version,
+        minVersion: inspection.minVersion
+      }),
+      t("doctor.check.global_cli_outdated.remediation")
+    );
+  }
+  if (inspection.status === "not-found") {
+    return issueCheck(
+      t("doctor.check.global_cli_outdated.name"),
+      "warn",
+      "warning",
+      "global_cli_not_found",
+      t("doctor.check.global_cli_outdated.message.not_found"),
+      t("doctor.check.global_cli_outdated.remediation")
+    );
+  }
+  return issueCheck(
+    t("doctor.check.global_cli_outdated.name"),
+    "warn",
+    "warning",
+    "global_cli_unparseable",
+    t("doctor.check.global_cli_outdated.message.unparseable", { detail: inspection.detail }),
+    t("doctor.check.global_cli_outdated.remediation")
+  );
+}
+var KNOWLEDGE_SUMMARY_OPAQUE_THRESHOLD = 0.3;
+function inspectKnowledgeSummaryOpaque(meta) {
+  const baseline = {
+    totalWithDescription: 0,
+    opaqueCount: 0,
+    ratio: 0,
+    threshold: KNOWLEDGE_SUMMARY_OPAQUE_THRESHOLD,
+    opaqueSample: []
+  };
+  if (!meta.valid || meta.meta === null) {
+    return { status: "skipped", ...baseline };
+  }
+  let total = 0;
+  const opaqueIds = [];
+  for (const node of Object.values(meta.meta.nodes)) {
+    const description = node.description;
+    const stableId = node.stable_id;
+    if (!description || typeof stableId !== "string" || stableId.length === 0) {
+      continue;
+    }
+    total += 1;
+    const summary = (description.summary ?? "").trim();
+    if (summary === stableId.trim()) {
+      opaqueIds.push(stableId);
+    }
+  }
+  if (total === 0) {
+    return { status: "ok", ...baseline };
+  }
+  const ratio = opaqueIds.length / total;
+  const status = ratio > KNOWLEDGE_SUMMARY_OPAQUE_THRESHOLD ? "warn" : "ok";
+  return {
+    status,
+    totalWithDescription: total,
+    opaqueCount: opaqueIds.length,
+    ratio,
+    threshold: KNOWLEDGE_SUMMARY_OPAQUE_THRESHOLD,
+    opaqueSample: opaqueIds.slice(0, 5)
+  };
+}
+function createKnowledgeSummaryOpaqueCheck(t, inspection) {
+  if (inspection.status === "skipped") {
+    return okCheck(
+      t("doctor.check.knowledge_summary_opaque.name"),
+      t("doctor.check.knowledge_summary_opaque.ok.skipped")
+    );
+  }
+  if (inspection.status === "ok") {
+    return okCheck(
+      t("doctor.check.knowledge_summary_opaque.name"),
+      t("doctor.check.knowledge_summary_opaque.ok", {
+        opaque: String(inspection.opaqueCount),
+        total: String(inspection.totalWithDescription)
+      })
+    );
+  }
+  const pct = Math.round(inspection.ratio * 1e3) / 10;
+  return issueCheck(
+    t("doctor.check.knowledge_summary_opaque.name"),
+    "warn",
+    "warning",
+    "knowledge_summary_opaque",
+    t("doctor.check.knowledge_summary_opaque.message.warn", {
+      opaque: String(inspection.opaqueCount),
+      total: String(inspection.totalWithDescription),
+      pct: String(pct),
+      threshold: String(Math.round(inspection.threshold * 100)),
+      sample: inspection.opaqueSample.join(", ")
+    }),
+    t("doctor.check.knowledge_summary_opaque.remediation")
+  );
+}
+function issueCheck(name, status, kind, code, message, actionHint, audience) {
   return {
     name,
     status,
@@ -3802,7 +4011,8 @@ function issueCheck(name, status, kind, code, message, actionHint) {
     code,
     fixable: kind === "fixable_error",
     message,
-    actionHint
+    actionHint,
+    audience
   };
 }
 function collectIssues(checks, kind) {
@@ -3810,7 +4020,8 @@ function collectIssues(checks, kind) {
     code: check.code ?? check.name,
     name: check.name,
     message: check.message,
-    actionHint: check.actionHint
+    actionHint: check.actionHint,
+    audience: check.audience
   }));
 }
 function findIssue(issues, code) {

package/dist/{http-2L2SQN7A.js → http-OHY2I6ZY.js}

@@ -14,7 +14,7 @@ import {
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-Z23PAA5L.js";
+} from "./chunk-DRIWYXFP.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -944,7 +944,7 @@ function toPosixPath(path) {
 function buildRecommendations(input) {
   const recommendations = [];
   if (!input.hasExistingFabric) {
-    recommendations.push("L0: Run `fab install` to scaffold the .fabric/ knowledge layout (decisions, pitfalls, guidelines, models, processes).");
+    recommendations.push("L0: Run `fabric install` to scaffold the .fabric/ knowledge layout (decisions, pitfalls, guidelines, models, processes).");
   }
   if (input.readmeQuality === "stub") {
     recommendations.push("L0: Expand README.md before promoting project facts into Fabric knowledge entries.");
@@ -980,7 +980,7 @@ function createLoopbackDenyMiddleware() {
       res,
       401,
       "UNAUTHORIZED",
-      "FABRIC_AUTH_TOKEN is not set. Either export FABRIC_AUTH_TOKEN=<secret> before running `fab serve`, or pass `--allow-loopback-no-auth` to explicitly opt in to unauthenticated loopback access (security risk)."
+      "FABRIC_AUTH_TOKEN is not set. Either export FABRIC_AUTH_TOKEN=<secret> before running `fabric serve`, or pass `--allow-loopback-no-auth` to explicitly opt in to unauthenticated loopback access (security risk)."
     );
   };
 }

package/dist/index.d.ts

@@ -32,6 +32,7 @@ type DoctorCheck = {
     code?: string;
     fixable?: boolean;
     actionHint?: string;
+    audience?: "user" | "maintainer";
 };
 type DoctorIssue = {
     code: string;
@@ -39,6 +40,7 @@ type DoctorIssue = {
     message: string;
     path?: string;
     actionHint?: string;
+    audience?: "user" | "maintainer";
 };
 type DoctorPayloadLimits = {
     warn_bytes: number;

package/dist/index.js

@@ -39,7 +39,7 @@ import {
   sha256,
   stableStringify,
   writeKnowledgeMeta
-} from "./chunk-Z23PAA5L.js";
+} from "./chunk-DRIWYXFP.js";
 
 // src/index.ts
 import { existsSync as existsSync3 } from "fs";
@@ -59,13 +59,13 @@ function gateWarning(result) {
     return {
       code: "meta_stale",
       file: "<response>",
-      action_hint: "Initial reconcile still pending; results may use cached meta. Retry shortly or run `fab doctor --fix`."
+      action_hint: "Initial reconcile still pending; results may use cached meta. Retry shortly or run `fabric doctor --fix`."
     };
   }
   return {
     code: "reconcile_failed",
     file: "<response>",
-    action_hint: "Reconcile failed at startup; run `fab doctor --fix` and restart the MCP server."
+    action_hint: "Reconcile failed at startup; run `fabric doctor --fix` and restart the MCP server."
   };
 }
 var state = {
@@ -297,7 +297,7 @@ async function extractKnowledge(projectRoot, input) {
     // v2.0.0-rc.23 TASK-014 (F8c): optional S5 onboard-slot tag. Same emit
     // discipline as the four a-C1 fields — bare YAML line iff caller-supplied,
     // never in the idempotency_key hash. fabric-archive's first-run phase is
-    // the only producer; downstream `fab onboard-coverage` walks frontmatter
+    // the only producer; downstream `fabric onboard-coverage` walks frontmatter
     // looking for this exact key.
     onboardSlot: input.onboard_slot
   });
@@ -2091,7 +2091,7 @@ function formatPreexistingRootMessage(projectRoot) {
 function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-knowledge-server",
-    version: "2.0.0-rc.34"
+    version: "2.0.0-rc.35"
   });
   registerPlanContext(server, tracker);
   registerKnowledgeSections(server, tracker);
@@ -2199,7 +2199,7 @@ function createShutdownHandler(deps) {
   };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-2L2SQN7A.js");
+  const { createFabricHttpApp } = await import("./http-OHY2I6ZY.js");
   const { port, projectRoot, host = "127.0.0.1", authToken, allowLoopbackNoAuth } = options;
   const app = createFabricHttpApp({ projectRoot, host, authToken, allowLoopbackNoAuth });
   return await new Promise((resolveServer, rejectServer) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.0.0-rc.34",
+  "version": "2.0.0-rc.35",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
     "express": "^5.2.1",
     "minimatch": "^10.0.1",
     "zod": "^3.25.0",
-    "@fenglimg/fabric-shared": "2.0.0-rc.34"
+    "@fenglimg/fabric-shared": "2.0.0-rc.35"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",