facult 2.7.7 → 2.8.1

package/README.md

@@ -43,6 +43,7 @@ Recommended global install:
 brew tap hack-dance/tap
 brew install hack-dance/tap/fclt
 fclt --help
+fclt --version
 ```
 
 Package-manager install:
@@ -89,10 +90,26 @@ fclt self-update --version 0.0.1
 
 ```bash
 fclt scan --show-duplicates
+fclt status
+fclt inventory --json
 ```
 
 `scan` is read-only. It inspects local configs and reports what `fclt` found without changing files.
 
+`status` reports the active canonical root, managed-tool state, generated index/graph state, writeback/proposal queue state, and high-signal sync risks.
+
+`inventory` is the stable machine-readable discovery surface for agent harnesses. It returns a JSON catalog of discovered MCP servers, skills, and instruction/rule assets across known tool configs and configured scan roots. MCP definitions are redacted by default, including env values, inline `KEY=value` args, bearer tokens, and secret-looking URL query params, but include safe auth metadata such as env keys, env references, and whether inline secret values were found.
+
+Useful inventory slices:
+
+```bash
+fclt inventory --json --global
+fclt inventory --json --project
+fclt inventory --json --tool codex
+```
+
+Use `mcpCapabilities` for the de-duplicated agent-facing MCP view. Use `mcpServers` when you need raw per-source occurrences for diagnostics.
+
 If you want a repo-local `.ai`:
 
 ```bash
@@ -137,6 +154,8 @@ If you run these commands inside a repo that has `<repo>/.ai`, `fclt` targets th
 
 ```bash
 fclt list skills
+fclt inventory --json
+fclt status --json
 fclt show instruction:WRITING
 fclt show mcp:github
 fclt find verification
@@ -514,6 +533,7 @@ Recommended security flow:
 - Inventory and discovery
 ```bash
 fclt scan [--from <path>] [--json] [--show-duplicates]
+fclt inventory [--from <path>] [--json] [--show-secrets]
 fclt list [skills|mcp|agents|snippets|instructions] [--enabled-for <tool>] [--untrusted] [--flagged] [--pending]
 fclt show <name>
 fclt show instruction:<name>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.7.7",
+  "version": "2.8.1",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "facult": "bun run ./src/index.ts",
     "scan": "bun run ./src/index.ts scan",
     "build": "bun run scripts/build-binary.ts",
-    "build:verify": "./dist/fclt --help",
+    "build:verify": "bun run scripts/verify-binary.ts",
     "install:dev": "bun run scripts/install-cli.ts --mode=dev --force",
     "install:bin": "bun run build && bun run scripts/install-cli.ts --mode=bin --force",
     "install:status": "bun run scripts/install-status.ts",

package/src/ai.ts

@@ -1545,6 +1545,11 @@ async function writebackCommand(argv: string[]) {
     return;
   }
 
+  if (parsed.argv.includes("--help") || parsed.argv.includes("-h")) {
+    console.log(writebackHelp());
+    return;
+  }
+
   const rootDir = resolveCliContextRoot({
     rootArg: parsed.rootArg,
     scope: parsed.scope,
@@ -1656,6 +1661,11 @@ async function evolveCommand(argv: string[]) {
     return;
   }
 
+  if (parsed.argv.includes("--help") || parsed.argv.includes("-h")) {
+    console.log(evolveHelp());
+    return;
+  }
+
   const rootDir = resolveCliContextRoot({
     rootArg: parsed.rootArg,
     scope: parsed.scope,

package/src/index.ts

@@ -108,6 +108,14 @@ function printHelp() {
             headers: ["Command", "Purpose"],
             rows: [
               ["scan", "Scan local tool configs and discovered assets"],
+              [
+                "inventory",
+                "Print a JSON inventory of usable skills, instructions, and MCP servers",
+              ],
+              [
+                "status",
+                "Show active roots, managed tools, graph/index, and sync risks",
+              ],
               [
                 "audit",
                 "Run security audits with interactive or scripted flows",
@@ -1253,6 +1261,12 @@ async function main(argv: string[]) {
     return;
   }
 
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    const { packageVersion } = await import("./status");
+    console.log(await packageVersion());
+    return;
+  }
+
   // Convenience: allow `fclt --show-duplicates` as shorthand for `fclt scan --show-duplicates`.
   if (cmd === "--show-duplicates") {
     const { scanCommand } = await import("./scan");
@@ -1264,6 +1278,14 @@ async function main(argv: string[]) {
     case "scan":
       await import("./scan").then(({ scanCommand }) => scanCommand(rest));
       return;
+    case "inventory":
+      await import("./inventory").then(({ inventoryCommand }) =>
+        inventoryCommand(rest)
+      );
+      return;
+    case "status":
+      await import("./status").then(({ statusCommand }) => statusCommand(rest));
+      return;
     case "audit":
       await import("./audit").then(({ auditCommand }) => auditCommand(rest));
       return;

package/src/inventory.ts

@@ -0,0 +1,886 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { extractServersObject } from "./mcp-config";
+import { facultRootDir, readFacultConfig } from "./paths";
+import type { AssetFile, McpConfig, ScanResult, SourceResult } from "./scan";
+import { scan } from "./scan";
+import { parseJsonLenient } from "./util/json";
+import { computeSkillOccurrences } from "./util/skills";
+
+export interface InventoryAuthSummary {
+  state: "none" | "env" | "inline-secret" | "external";
+  envKeys: string[];
+  envRefs: string[];
+  inlineSecretKeys: string[];
+  hasInlineSecrets: boolean;
+  notes: string[];
+}
+
+export interface InventoryMcpServer {
+  name: string;
+  sourceId: string;
+  sourceName: string;
+  configPath: string;
+  configFormat: McpConfig["format"];
+  transport?: string;
+  command?: string;
+  args?: string[];
+  url?: string;
+  auth: InventoryAuthSummary;
+  definition: unknown;
+}
+
+export interface InventoryMcpCapability {
+  name: string;
+  occurrences: number;
+  sourceIds: string[];
+  sourceNames: string[];
+  configPaths: string[];
+  variants: number;
+  authStates: InventoryAuthSummary["state"][];
+  hasInlineSecrets: boolean;
+  preferred: InventoryMcpServer;
+}
+
+export interface InventorySkill {
+  name: string;
+  path: string;
+  sourceIds: string[];
+  sourceNames: string[];
+  occurrences: number;
+}
+
+export interface InventoryInstruction {
+  kind: string;
+  path: string;
+  sourceId: string;
+  sourceName: string;
+  format: AssetFile["format"];
+  summary?: Record<string, unknown>;
+}
+
+export interface InventorySource {
+  id: string;
+  name: string;
+  found: boolean;
+  roots: string[];
+  evidence: string[];
+  warnings?: string[];
+  truncated?: boolean;
+}
+
+export interface AgentInventory {
+  version: 1;
+  generatedAt: string;
+  cwd: string;
+  canonicalRoot: string;
+  scanFrom: string[];
+  sources: InventorySource[];
+  mcpCapabilities: InventoryMcpCapability[];
+  mcpServers: InventoryMcpServer[];
+  skills: InventorySkill[];
+  instructions: InventoryInstruction[];
+  summary: {
+    sourceCount: number;
+    mcpCapabilityCount: number;
+    mcpServerCount: number;
+    skillCount: number;
+    instructionCount: number;
+    warningCount: number;
+    truncatedSourceCount: number;
+  };
+}
+
+interface InventoryOptions {
+  cwd?: string;
+  homeDir?: string;
+  from?: string[];
+  includeConfigFrom?: boolean;
+  includeGitHooks?: boolean;
+  showSecrets?: boolean;
+  sourceMode?: "machine" | "global" | "project";
+  tool?: string;
+}
+
+const SECRET_KEY_RE = /(TOKEN|KEY|SECRET|PASSWORD|PASS|BEARER|AUTH)/i;
+const ENV_REF_RE = /^\$?\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/;
+const SECRETY_STRING_RE =
+  /\b(sk-[A-Za-z0-9]{10,}|ghp_[A-Za-z0-9]{10,}|github_pat_[A-Za-z0-9_]{10,})\b/g;
+const SECRET_ASSIGNMENT_RE =
+  /\b([A-Za-z0-9_-]*(?:TOKEN|KEY|SECRET|PASSWORD|PASS|BEARER|AUTH)[A-Za-z0-9_-]*)\s*=\s*("([^"]*)"|'([^']*)'|[^\s"'&]+)/gi;
+const SECRET_URL_PARAM_RE =
+  /([?&][A-Za-z0-9_.-]*(?:token|key|secret|password|pass|bearer|auth)[A-Za-z0-9_.-]*=)([^&#\s"']+)/gi;
+const BEARER_RE = /\bBearer\s+([A-Za-z0-9._~+/=-]{10,})\b/gi;
+const URL_QUERY_KEY_PREFIX_RE = /^[?&]/;
+const TRAILING_EQUALS_RE = /=$/;
+
+function isPlaceholderSecretValue(value: string): boolean {
+  const trimmed = value.trim();
+  return (
+    !trimmed ||
+    trimmed === "<redacted>" ||
+    trimmed === "<set-me>" ||
+    extractEnvRef(trimmed) !== null
+  );
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function redactPossibleSecrets(value: string): string {
+  return value
+    .replace(SECRET_ASSIGNMENT_RE, (_match, key: string, rawValue: string) => {
+      const quote =
+        rawValue.startsWith('"') || rawValue.startsWith("'") ? rawValue[0] : "";
+      return `${key}=${quote}<redacted>${quote}`;
+    })
+    .replace(SECRET_URL_PARAM_RE, "$1<redacted>")
+    .replace(BEARER_RE, "Bearer <redacted>")
+    .replace(SECRETY_STRING_RE, "<redacted>");
+}
+
+function sanitizeDefinition(value: unknown): unknown {
+  if (typeof value === "string") {
+    return redactPossibleSecrets(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitizeDefinition);
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, inner] of Object.entries(value)) {
+    if (SECRET_KEY_RE.test(key)) {
+      out[key] = "<redacted>";
+      continue;
+    }
+    out[key] = sanitizeDefinition(inner);
+  }
+  return out;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  return value.map((entry) => String(entry));
+}
+
+function safeStringArray(value: unknown, opts: { showSecrets: boolean }) {
+  const values = stringArray(value);
+  if (!values) {
+    return undefined;
+  }
+  return opts.showSecrets ? values : values.map(redactPossibleSecrets);
+}
+
+function extractEnvRef(value: string): string | null {
+  const trimmed = value.trim();
+  if (!(trimmed.startsWith("$") || trimmed.startsWith("${"))) {
+    return null;
+  }
+  const match = ENV_REF_RE.exec(trimmed);
+  return match?.[1] ?? null;
+}
+
+function addStringSecretFindings(args: {
+  value: string;
+  location: string;
+  inlineSecretKeys: Set<string>;
+}) {
+  const { value, location, inlineSecretKeys } = args;
+  for (const match of value.matchAll(SECRET_ASSIGNMENT_RE)) {
+    const key = match[1]?.trim();
+    const rawValue = (match[3] ?? match[4] ?? match[2] ?? "").trim();
+    if (key && !isPlaceholderSecretValue(rawValue)) {
+      inlineSecretKeys.add(`${location}:${key}`);
+    }
+  }
+
+  for (const match of value.matchAll(SECRET_URL_PARAM_RE)) {
+    const rawKey = match[1] ?? "";
+    const rawValue = match[2] ?? "";
+    const key = rawKey
+      .replace(URL_QUERY_KEY_PREFIX_RE, "")
+      .replace(TRAILING_EQUALS_RE, "");
+    if (key && !isPlaceholderSecretValue(rawValue)) {
+      inlineSecretKeys.add(`${location}:${key}`);
+    }
+  }
+
+  if (BEARER_RE.test(value) || SECRETY_STRING_RE.test(value)) {
+    inlineSecretKeys.add(location);
+  }
+  BEARER_RE.lastIndex = 0;
+  SECRETY_STRING_RE.lastIndex = 0;
+}
+
+function summarizeAuth(definition: unknown): InventoryAuthSummary {
+  const envKeys = new Set<string>();
+  const envRefs = new Set<string>();
+  const inlineSecretKeys = new Set<string>();
+  const notes: string[] = [];
+
+  if (!isPlainObject(definition)) {
+    return {
+      state: "none",
+      envKeys: [],
+      envRefs: [],
+      inlineSecretKeys: [],
+      hasInlineSecrets: false,
+      notes,
+    };
+  }
+
+  const env = definition.env;
+  if (isPlainObject(env)) {
+    for (const [key, value] of Object.entries(env)) {
+      envKeys.add(key);
+      if (typeof value !== "string") {
+        continue;
+      }
+      const ref = extractEnvRef(value);
+      if (ref) {
+        envRefs.add(ref);
+        continue;
+      }
+      if (SECRET_KEY_RE.test(key) && !isPlaceholderSecretValue(value)) {
+        inlineSecretKeys.add(key);
+      }
+    }
+  }
+
+  const inspectValue = (value: unknown, location: string) => {
+    if (typeof value === "string") {
+      addStringSecretFindings({ value, location, inlineSecretKeys });
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const [index, entry] of value.entries()) {
+        inspectValue(entry, `${location}[${index}]`);
+      }
+      return;
+    }
+    if (!isPlainObject(value)) {
+      return;
+    }
+    for (const [key, inner] of Object.entries(value)) {
+      const childLocation = location ? `${location}.${key}` : key;
+      if (typeof inner === "string") {
+        const ref = extractEnvRef(inner);
+        if (ref) {
+          envRefs.add(ref);
+        } else if (
+          SECRET_KEY_RE.test(key) &&
+          !isPlaceholderSecretValue(inner)
+        ) {
+          inlineSecretKeys.add(childLocation);
+        }
+      }
+      inspectValue(inner, childLocation);
+    }
+  };
+  inspectValue(definition, "");
+
+  const command =
+    typeof definition.command === "string" ? definition.command : "";
+  if (envKeys.size === 0 && command && inlineSecretKeys.size === 0) {
+    notes.push(
+      "No explicit MCP env auth found; server may rely on external CLI/session auth."
+    );
+  }
+
+  const uniqueEnvKeys = [...envKeys].sort();
+  const uniqueEnvRefs = [...envRefs].sort();
+  const uniqueInlineSecretKeys = [...inlineSecretKeys].sort();
+  const hasInlineSecrets = uniqueInlineSecretKeys.length > 0;
+  const state = hasInlineSecrets
+    ? "inline-secret"
+    : uniqueEnvKeys.length || uniqueEnvRefs.length
+      ? "env"
+      : command
+        ? "external"
+        : "none";
+
+  return {
+    state,
+    envKeys: uniqueEnvKeys,
+    envRefs: uniqueEnvRefs,
+    inlineSecretKeys: uniqueInlineSecretKeys,
+    hasInlineSecrets,
+    notes,
+  };
+}
+
+async function loadMcpServerDefinitions(
+  config: McpConfig
+): Promise<Record<string, unknown>> {
+  try {
+    const raw = await Bun.file(config.path).text();
+    if (config.format === "toml") {
+      const parsed = Bun.TOML.parse(raw) as Record<string, unknown>;
+      const servers = parsed.mcp_servers;
+      return isPlainObject(servers) ? servers : {};
+    }
+    const parsed = parseJsonLenient(raw);
+    return extractServersObject(parsed) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+async function inventoryMcpServers(
+  result: ScanResult,
+  opts: { showSecrets: boolean }
+): Promise<InventoryMcpServer[]> {
+  const out: InventoryMcpServer[] = [];
+  for (const source of result.sources) {
+    for (const config of source.mcp.configs) {
+      const definitions = await loadMcpServerDefinitions(config);
+      for (const name of Object.keys(definitions).sort()) {
+        const rawDefinition = definitions[name];
+        const definition = opts.showSecrets
+          ? rawDefinition
+          : sanitizeDefinition(rawDefinition);
+        const obj = isPlainObject(rawDefinition) ? rawDefinition : {};
+        out.push({
+          name,
+          sourceId: source.id,
+          sourceName: source.name,
+          configPath: config.path,
+          configFormat: config.format,
+          transport:
+            typeof obj.transport === "string" ? obj.transport : undefined,
+          command:
+            typeof obj.command === "string"
+              ? opts.showSecrets
+                ? obj.command
+                : redactPossibleSecrets(obj.command)
+              : undefined,
+          args: safeStringArray(obj.args, opts),
+          url:
+            typeof obj.url === "string"
+              ? opts.showSecrets
+                ? obj.url
+                : redactPossibleSecrets(obj.url)
+              : undefined,
+          auth: summarizeAuth(rawDefinition),
+          definition,
+        });
+      }
+    }
+  }
+  return out.sort(
+    (a, b) =>
+      a.name.localeCompare(b.name) ||
+      a.sourceId.localeCompare(b.sourceId) ||
+      a.configPath.localeCompare(b.configPath)
+  );
+}
+
+function inventorySourceRank(sourceId: string): number {
+  if (sourceId === "facult") {
+    return 0;
+  }
+  if (sourceId === "codex") {
+    return 1;
+  }
+  if (sourceId.endsWith("-project")) {
+    return 2;
+  }
+  if (sourceId === "claude" || sourceId === "factory") {
+    return 3;
+  }
+  if (sourceId.startsWith("from-")) {
+    return 9;
+  }
+  return 5;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+  if (!isPlainObject(value)) {
+    return JSON.stringify(value);
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+    .join(",")}}`;
+}
+
+function preferredMcpServer(servers: InventoryMcpServer[]): InventoryMcpServer {
+  return [...servers].sort((a, b) => {
+    const sourceDiff =
+      inventorySourceRank(a.sourceId) - inventorySourceRank(b.sourceId);
+    if (sourceDiff !== 0) {
+      return sourceDiff;
+    }
+    return a.configPath.localeCompare(b.configPath);
+  })[0]!;
+}
+
+function inventoryMcpCapabilities(
+  servers: InventoryMcpServer[]
+): InventoryMcpCapability[] {
+  const byName = new Map<string, InventoryMcpServer[]>();
+  for (const server of servers) {
+    byName.set(server.name, [...(byName.get(server.name) ?? []), server]);
+  }
+
+  return [...byName.entries()]
+    .map(([name, entries]) => ({
+      name,
+      occurrences: entries.length,
+      sourceIds: [...new Set(entries.map((entry) => entry.sourceId))].sort(),
+      sourceNames: [
+        ...new Set(entries.map((entry) => entry.sourceName)),
+      ].sort(),
+      configPaths: [
+        ...new Set(entries.map((entry) => entry.configPath)),
+      ].sort(),
+      variants: new Set(entries.map((entry) => stableJson(entry.definition)))
+        .size,
+      authStates: [...new Set(entries.map((entry) => entry.auth.state))].sort(),
+      hasInlineSecrets: entries.some((entry) => entry.auth.hasInlineSecrets),
+      preferred: preferredMcpServer(entries),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function sourceMatchesInventoryOptions(
+  sourceId: string,
+  opts: Pick<InventoryOptions, "sourceMode" | "tool">
+): boolean {
+  if (opts.tool) {
+    return sourceId === opts.tool || sourceId === `${opts.tool}-project`;
+  }
+  if (opts.sourceMode === "global") {
+    return !(sourceId.endsWith("-project") || sourceId.startsWith("from-"));
+  }
+  if (opts.sourceMode === "project") {
+    return sourceId.endsWith("-project") || sourceId.startsWith("from-");
+  }
+  return true;
+}
+
+function filterInventoryBySource(
+  inventory: AgentInventory,
+  opts: Pick<InventoryOptions, "sourceMode" | "tool">
+): AgentInventory {
+  if (!((opts.sourceMode && opts.sourceMode !== "machine") || opts.tool)) {
+    return inventory;
+  }
+
+  const sources = inventory.sources.filter((source) =>
+    sourceMatchesInventoryOptions(source.id, opts)
+  );
+  const sourceIds = new Set(sources.map((source) => source.id));
+  const mcpServers = inventory.mcpServers.filter((server) =>
+    sourceIds.has(server.sourceId)
+  );
+  const skills = inventory.skills
+    .map((skill) => {
+      const keptSourceIds = skill.sourceIds.filter((id) => sourceIds.has(id));
+      if (keptSourceIds.length === 0) {
+        return null;
+      }
+      return {
+        ...skill,
+        sourceIds: keptSourceIds,
+        sourceNames: skill.sourceNames.filter((name) =>
+          sources.some((source) => source.name === name)
+        ),
+        occurrences: keptSourceIds.length,
+      };
+    })
+    .filter((skill): skill is InventorySkill => skill !== null);
+  const instructions = inventory.instructions.filter((instruction) =>
+    sourceIds.has(instruction.sourceId)
+  );
+  const mcpCapabilities = inventoryMcpCapabilities(mcpServers);
+  const warningCount = sources.reduce(
+    (count, source) => count + (source.warnings?.length ?? 0),
+    0
+  );
+
+  return {
+    ...inventory,
+    sources,
+    mcpCapabilities,
+    mcpServers,
+    skills,
+    instructions,
+    summary: {
+      sourceCount: sources.filter((source) => source.found).length,
+      mcpCapabilityCount: mcpCapabilities.length,
+      mcpServerCount: mcpServers.length,
+      skillCount: skills.length,
+      instructionCount: instructions.length,
+      warningCount,
+      truncatedSourceCount: sources.filter((source) => source.truncated).length,
+    },
+  };
+}
+
+function inventorySkills(result: ScanResult): InventorySkill[] {
+  const occurrences = computeSkillOccurrences(result);
+  return occurrences
+    .map((entry) => {
+      const sourceIds = new Set<string>();
+      const sourceNames = new Set<string>();
+      for (const location of entry.locations) {
+        const i = location.indexOf(":");
+        if (i <= 0) {
+          continue;
+        }
+        const sourceId = location.slice(0, i);
+        sourceIds.add(sourceId);
+        const source = result.sources.find(
+          (candidate) => candidate.id === sourceId
+        );
+        if (source) {
+          sourceNames.add(source.name);
+        }
+      }
+      return {
+        name: entry.name,
+        path:
+          entry.locations[0]?.slice(entry.locations[0].indexOf(":") + 1) ?? "",
+        sourceIds: [...sourceIds].sort(),
+        sourceNames: [...sourceNames].sort(),
+        occurrences: entry.count,
+      };
+    })
+    .sort(
+      (a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path)
+    );
+}
+
+function isInstructionAsset(kind: string): boolean {
+  return (
+    kind.includes("instruction") ||
+    kind.includes("rule") ||
+    kind === "claude-settings" ||
+    kind === "cursor-hook"
+  );
+}
+
+async function listMarkdownFiles(root: string): Promise<string[]> {
+  try {
+    const stat = await Bun.file(root).stat();
+    if (!stat.isDirectory()) {
+      return [];
+    }
+  } catch {
+    return [];
+  }
+
+  const out: string[] = [];
+  const glob = new Bun.Glob("**/*.md");
+  for await (const rel of glob.scan({ cwd: root, onlyFiles: true })) {
+    out.push(join(root, rel));
+  }
+  return out.sort();
+}
+
+async function canonicalInstructionAssets(
+  source: SourceResult
+): Promise<InventoryInstruction[]> {
+  const out: InventoryInstruction[] = [];
+  for (const root of source.roots) {
+    const candidates = [
+      ...(await listMarkdownFiles(join(root, "instructions"))).map((path) => ({
+        kind: "canonical-instruction",
+        path,
+      })),
+      { kind: "agents-instructions", path: join(root, "AGENTS.global.md") },
+      {
+        kind: "agents-instructions",
+        path: join(root, "AGENTS.override.global.md"),
+      },
+    ];
+    for (const candidate of candidates) {
+      try {
+        const stat = await Bun.file(candidate.path).stat();
+        if (!stat.isFile()) {
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      out.push({
+        kind: candidate.kind,
+        path: candidate.path,
+        sourceId: source.id,
+        sourceName: source.name,
+        format: "markdown",
+      });
+    }
+  }
+  return out;
+}
+
+async function inventoryInstructions(
+  result: ScanResult
+): Promise<InventoryInstruction[]> {
+  const out: InventoryInstruction[] = [];
+  for (const source of result.sources) {
+    for (const asset of source.assets.files) {
+      if (!isInstructionAsset(asset.kind)) {
+        continue;
+      }
+      out.push({
+        kind: asset.kind,
+        path: asset.path,
+        sourceId: source.id,
+        sourceName: source.name,
+        format: asset.format,
+        summary: asset.summary,
+      });
+    }
+    if (source.id === "facult" || source.id.endsWith("-project")) {
+      out.push(...(await canonicalInstructionAssets(source)));
+    }
+  }
+
+  const seen = new Set<string>();
+  return out
+    .filter((entry) => {
+      const key = `${entry.kind}\0${entry.path}\0${entry.sourceId}`;
+      if (seen.has(key)) {
+        return false;
+      }
+      seen.add(key);
+      return true;
+    })
+    .sort(
+      (a, b) =>
+        a.kind.localeCompare(b.kind) ||
+        a.sourceId.localeCompare(b.sourceId) ||
+        a.path.localeCompare(b.path)
+    );
+}
+
+function configuredScanFrom(homeDir: string): string[] {
+  const config = readFacultConfig(homeDir);
+  return [...(config?.scanFrom ?? [])].sort();
+}
+
+export async function buildAgentInventory(
+  opts?: InventoryOptions
+): Promise<AgentInventory> {
+  const homeDir = opts?.homeDir ?? homedir();
+  const cwd = opts?.cwd ?? process.cwd();
+  const includeConfigFrom = opts?.includeConfigFrom ?? true;
+  const configuredFrom = includeConfigFrom ? configuredScanFrom(homeDir) : [];
+  const explicitFrom = opts?.from ?? [];
+  const effectiveFrom =
+    configuredFrom.length === 0 && explicitFrom.length === 0
+      ? opts?.sourceMode === "project"
+        ? [cwd]
+        : ["~"]
+      : explicitFrom;
+  const scanResult = await scan([], {
+    cwd,
+    homeDir,
+    includeConfigFrom,
+    includeGitHooks: opts?.includeGitHooks,
+    from: effectiveFrom,
+  });
+  const [mcpServers, skills, instructions] = await Promise.all([
+    inventoryMcpServers(scanResult, {
+      showSecrets: opts?.showSecrets ?? false,
+    }),
+    Promise.resolve(inventorySkills(scanResult)),
+    inventoryInstructions(scanResult),
+  ]);
+  const mcpCapabilities = inventoryMcpCapabilities(mcpServers);
+  const sources = scanResult.sources.map((source) => ({
+    id: source.id,
+    name: source.name,
+    found: source.found,
+    roots: source.roots,
+    evidence: source.evidence,
+    warnings: source.warnings,
+    truncated: source.truncated,
+  }));
+  const warningCount = sources.reduce(
+    (count, source) => count + (source.warnings?.length ?? 0),
+    0
+  );
+
+  const inventory: AgentInventory = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    cwd,
+    canonicalRoot: facultRootDir(homeDir),
+    scanFrom: [...new Set([...configuredFrom, ...effectiveFrom])].sort(),
+    sources,
+    mcpCapabilities,
+    mcpServers,
+    skills,
+    instructions,
+    summary: {
+      sourceCount: sources.filter((source) => source.found).length,
+      mcpCapabilityCount: mcpCapabilities.length,
+      mcpServerCount: mcpServers.length,
+      skillCount: skills.length,
+      instructionCount: instructions.length,
+      warningCount,
+      truncatedSourceCount: sources.filter((source) => source.truncated).length,
+    },
+  };
+  return filterInventoryBySource(inventory, {
+    sourceMode: opts?.sourceMode,
+    tool: opts?.tool,
+  });
+}
+
+function printHelp() {
+  console.log(`fclt inventory — machine-readable agent capability inventory
+
+Usage:
+  fclt inventory --json
+  fclt inventory --from <path> --json
+
+Options:
+  --json              Print JSON. This command is JSON-first.
+  --from              Add one or more scan roots (repeatable)
+  --show-secrets      Include raw MCP definitions instead of redacted definitions
+  --include-git-hooks Include git hooks and Husky hooks in instruction assets
+  --no-config-from    Disable scanFrom roots from ~/.ai/.facult/config.json
+  --global            Show global/non-project sources only
+  --project           Show project-local sources only
+  --tool <name>       Show sources for one tool id, such as codex or claude
+`);
+}
+
+export function parseInventoryArgs(argv: string[]): {
+  json: boolean;
+  showSecrets: boolean;
+  includeGitHooks: boolean;
+  includeConfigFrom: boolean;
+  sourceMode: "machine" | "global" | "project";
+  tool?: string;
+  from: string[];
+} {
+  let json = false;
+  let showSecrets = false;
+  let includeGitHooks = false;
+  let includeConfigFrom = true;
+  let sourceMode: "machine" | "global" | "project" = "machine";
+  let tool: string | undefined;
+  const from: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg === "--show-secrets") {
+      showSecrets = true;
+      continue;
+    }
+    if (arg === "--include-git-hooks") {
+      includeGitHooks = true;
+      continue;
+    }
+    if (arg === "--no-config-from") {
+      includeConfigFrom = false;
+      continue;
+    }
+    if (arg === "--global") {
+      if (sourceMode === "project") {
+        throw new Error("Conflicting scope flags");
+      }
+      sourceMode = "global";
+      continue;
+    }
+    if (arg === "--project") {
+      if (sourceMode === "global") {
+        throw new Error("Conflicting scope flags");
+      }
+      sourceMode = "project";
+      continue;
+    }
+    if (arg === "--tool") {
+      const next = argv[i + 1];
+      if (!next) {
+        throw new Error("--tool requires a name");
+      }
+      tool = next;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--tool=")) {
+      const value = arg.slice("--tool=".length);
+      if (!value) {
+        throw new Error("--tool requires a name");
+      }
+      tool = value;
+      continue;
+    }
+    if (arg === "--from") {
+      const next = argv[i + 1];
+      if (!next) {
+        throw new Error("--from requires a path");
+      }
+      from.push(next);
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--from=")) {
+      const value = arg.slice("--from=".length);
+      if (!value) {
+        throw new Error("--from requires a path");
+      }
+      from.push(value);
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+  return {
+    json,
+    showSecrets,
+    includeGitHooks,
+    includeConfigFrom,
+    sourceMode,
+    tool,
+    from,
+  };
+}
+
+export async function inventoryCommand(argv: string[]) {
+  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+    printHelp();
+    return;
+  }
+
+  let opts: ReturnType<typeof parseInventoryArgs>;
+  try {
+    opts = parseInventoryArgs(argv);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 2;
+    return;
+  }
+
+  const inventory = await buildAgentInventory({
+    from: opts.from,
+    showSecrets: opts.showSecrets,
+    includeGitHooks: opts.includeGitHooks,
+    includeConfigFrom: opts.includeConfigFrom,
+    sourceMode: opts.sourceMode,
+    tool: opts.tool,
+  });
+
+  console.log(`${JSON.stringify(inventory, null, 2)}\n`);
+}

package/src/mcp-config.ts

@@ -32,6 +32,11 @@ export function extractServersObject(
     return null;
   }
   const raw = parsed as Record<string, unknown>;
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.endsWith(".mcpServers") && isPlainObject(value)) {
+      return value as Record<string, unknown>;
+    }
+  }
   const servers =
     (raw.servers as Record<string, unknown> | undefined) ??
     (raw.mcpServers as Record<string, unknown> | undefined) ??

package/src/scan.ts

@@ -1189,6 +1189,44 @@ async function buildFromRootResult(args: {
     }
   };
 
+  const scanAiDir = async (aiDir: string) => {
+    await scanToolDotDir(aiDir);
+
+    for (const name of ["servers.json", "mcp.json"]) {
+      const p = join(aiDir, "mcp", name);
+      if ((await statSafe(p))?.isFile) {
+        if (addResult(1)) {
+          mcpConfigPaths.add(p);
+        } else {
+          return;
+        }
+      }
+    }
+
+    for (const name of ["AGENTS.global.md", "AGENTS.override.global.md"]) {
+      const p = join(aiDir, name);
+      if ((await statSafe(p))?.isFile) {
+        addAsset("agents-instructions", p);
+      }
+    }
+
+    const instructionsDir = join(aiDir, "instructions");
+    if ((await statSafe(instructionsDir))?.isDir) {
+      const files = await listFilesRecursive(instructionsDir, {
+        ignore: args.opts.ignoreDirNames,
+        maxFiles: 2000,
+      });
+      for (const f of files) {
+        if (f.endsWith(".md")) {
+          addAsset("canonical-instruction", f);
+        }
+        if (truncated) {
+          break;
+        }
+      }
+    }
+  };
+
   const MCP_NAMES = new Set([
     "mcp.json",
     "mcp.config.json",
@@ -1317,6 +1355,10 @@ async function buildFromRootResult(args: {
         await scanToolDotDir(child);
         continue;
       }
+      if (name === ".ai") {
+        await scanAiDir(child);
+        continue;
+      }
 
       // Skills directories are typically called "skills"; scan them and don't descend further.
       if (name === "skills") {

package/src/status.ts

@@ -0,0 +1,287 @@
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
+import { loadManagedState } from "./manage";
+import {
+  facultAiGraphPath,
+  facultAiIndexPath,
+  facultAiProposalDir,
+  facultAiWritebackQueuePath,
+  facultMachineStateDir,
+  facultRootDir,
+  projectRootFromAiRoot,
+} from "./paths";
+import { parseJsonLenient } from "./util/json";
+
+declare const FCLT_COMPILED_VERSION: string | undefined;
+
+export interface StatusIssue {
+  severity: "info" | "warning" | "error";
+  code: string;
+  message: string;
+}
+
+export interface FacultStatus {
+  version: 1;
+  packageVersion: string;
+  cwd: string;
+  globalRoot: string;
+  contextRoot: string;
+  projectRoot: string | null;
+  machineStateDir: string;
+  managedTools: string[];
+  generatedOnlyProjectRoot: boolean;
+  index: {
+    path: string;
+    exists: boolean;
+  };
+  graph: {
+    path: string;
+    exists: boolean;
+  };
+  writeback: {
+    queuePath: string;
+    pendingCount: number;
+    proposalDir: string;
+    proposalCount: number;
+  };
+  issues: StatusIssue[];
+}
+
+async function fileExists(pathValue: string): Promise<boolean> {
+  try {
+    return (await Bun.file(pathValue).stat()).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function dirHasVisibleEntries(pathValue: string): Promise<boolean> {
+  const entries = await readdir(pathValue).catch(() => [] as string[]);
+  return entries.some((entry) => !entry.startsWith("."));
+}
+
+async function hasCanonicalSource(rootDir: string): Promise<boolean> {
+  for (const relPath of [
+    "config.toml",
+    "config.local.toml",
+    "AGENTS.global.md",
+    "AGENTS.override.global.md",
+  ]) {
+    if (await fileExists(join(rootDir, relPath))) {
+      return true;
+    }
+  }
+
+  for (const relPath of [
+    "agents",
+    "automations",
+    "instructions",
+    "mcp",
+    "rules",
+    "skills",
+    "snippets",
+    "tools",
+  ]) {
+    if (await dirHasVisibleEntries(join(rootDir, relPath))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function countPendingWritebacks(
+  homeDir: string,
+  rootDir: string
+): Promise<number> {
+  const { listWritebacks } = await import("./ai");
+  const rows = await listWritebacks({ homeDir, rootDir }).catch(() => []);
+  return rows.filter(
+    (row) =>
+      row.status !== "dismissed" &&
+      row.status !== "promoted" &&
+      row.status !== "resolved" &&
+      row.status !== "superseded"
+  ).length;
+}
+
+async function countActiveProposals(
+  homeDir: string,
+  rootDir: string
+): Promise<number> {
+  const { listProposals } = await import("./ai");
+  const rows = await listProposals({ homeDir, rootDir }).catch(() => []);
+  return rows.filter(
+    (row) =>
+      row.status !== "applied" &&
+      row.status !== "failed" &&
+      row.status !== "rejected" &&
+      row.status !== "superseded"
+  ).length;
+}
+
+export async function packageVersion(): Promise<string> {
+  const envVersion =
+    process.env.FACULT_NPM_PACKAGE_VERSION ?? process.env.npm_package_version;
+  if (envVersion?.trim()) {
+    return envVersion.trim();
+  }
+
+  if (
+    typeof FCLT_COMPILED_VERSION === "string" &&
+    FCLT_COMPILED_VERSION.trim()
+  ) {
+    return FCLT_COMPILED_VERSION.trim();
+  }
+
+  const packagePath = join(dirname(import.meta.dir), "package.json");
+  const parsed = parseJsonLenient(
+    await Bun.file(packagePath)
+      .text()
+      .catch(() => "{}")
+  );
+  if (
+    parsed &&
+    typeof parsed === "object" &&
+    !Array.isArray(parsed) &&
+    typeof (parsed as Record<string, unknown>).version === "string"
+  ) {
+    const version = (parsed as Record<string, unknown>).version;
+    return typeof version === "string" ? version : "unknown";
+  }
+  return "unknown";
+}
+
+export async function buildStatus(opts?: {
+  cwd?: string;
+  homeDir?: string;
+  rootArg?: string;
+  scope?: "merged" | "global" | "project";
+}): Promise<FacultStatus> {
+  const homeDir = opts?.homeDir ?? process.env.HOME ?? "";
+  const cwd = opts?.cwd ?? process.cwd();
+  const globalRoot = facultRootDir(homeDir);
+  const contextRoot = resolveCliContextRoot({
+    homeDir,
+    cwd,
+    rootArg: opts?.rootArg,
+    scope: opts?.scope,
+  });
+  const projectRoot = projectRootFromAiRoot(contextRoot, homeDir);
+  const generatedOnlyProjectRoot =
+    projectRoot !== null && !(await hasCanonicalSource(contextRoot));
+  const indexPath = facultAiIndexPath(homeDir, contextRoot);
+  const graphPath = facultAiGraphPath(homeDir, contextRoot);
+  const queuePath = facultAiWritebackQueuePath(homeDir, contextRoot);
+  const proposalDir = facultAiProposalDir(homeDir, contextRoot);
+  const managed = await loadManagedState(homeDir, contextRoot);
+
+  const issues: StatusIssue[] = [];
+  if (generatedOnlyProjectRoot) {
+    issues.push({
+      severity: "warning",
+      code: "project-generated-only",
+      message:
+        "Project .ai contains generated state only; managed project sync should stay paused until canonical source is restored or initialized.",
+    });
+  }
+  if (!(await fileExists(indexPath))) {
+    issues.push({
+      severity: "info",
+      code: "missing-index",
+      message:
+        'Generated AI index is missing. Run "fclt index" after canonical source changes.',
+    });
+  }
+  if (!(await fileExists(graphPath))) {
+    issues.push({
+      severity: "info",
+      code: "missing-graph",
+      message: 'Generated AI graph is missing. Run "fclt index" to rebuild it.',
+    });
+  }
+
+  return {
+    version: 1,
+    packageVersion: await packageVersion(),
+    cwd,
+    globalRoot,
+    contextRoot,
+    projectRoot,
+    machineStateDir: facultMachineStateDir(homeDir, contextRoot),
+    managedTools: Object.keys(managed.tools).sort(),
+    generatedOnlyProjectRoot,
+    index: {
+      path: indexPath,
+      exists: await fileExists(indexPath),
+    },
+    graph: {
+      path: graphPath,
+      exists: await fileExists(graphPath),
+    },
+    writeback: {
+      queuePath,
+      pendingCount: await countPendingWritebacks(homeDir, contextRoot),
+      proposalDir,
+      proposalCount: await countActiveProposals(homeDir, contextRoot),
+    },
+    issues,
+  };
+}
+
+function printStatus(status: FacultStatus) {
+  console.log(`fclt ${status.packageVersion}`);
+  console.log(`cwd: ${status.cwd}`);
+  console.log(`global root: ${status.globalRoot}`);
+  console.log(`context root: ${status.contextRoot}`);
+  console.log(`project root: ${status.projectRoot ?? "(none)"}`);
+  console.log(`machine state: ${status.machineStateDir}`);
+  console.log(`managed tools: ${status.managedTools.join(", ") || "(none)"}`);
+  console.log(
+    `index: ${status.index.exists ? "present" : "missing"} (${status.index.path})`
+  );
+  console.log(
+    `graph: ${status.graph.exists ? "present" : "missing"} (${status.graph.path})`
+  );
+  console.log(
+    `writeback: ${status.writeback.pendingCount} queued, ${status.writeback.proposalCount} proposals`
+  );
+  if (status.issues.length > 0) {
+    console.log("issues:");
+    for (const issue of status.issues) {
+      console.log(`- [${issue.severity}] ${issue.code}: ${issue.message}`);
+    }
+  }
+}
+
+export async function statusCommand(argv: string[]) {
+  const parsed = parseCliContextArgs(argv);
+  if (
+    parsed.argv.includes("--help") ||
+    parsed.argv.includes("-h") ||
+    parsed.argv[0] === "help"
+  ) {
+    console.log(`fclt status
+
+Usage:
+  fclt status [--json] [--global|--project|--root <path>]
+
+Print the active canonical root, managed-tool state, generated index/graph state,
+writeback counts, and high-signal sync risks.
+`);
+    return;
+  }
+
+  const status = await buildStatus({
+    rootArg: parsed.rootArg,
+    scope: parsed.scope,
+    cwd: process.cwd(),
+  });
+
+  if (parsed.argv.includes("--json")) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+  printStatus(status);
+}