facult 2.5.2 → 2.7.0

package/README.md

@@ -444,7 +444,9 @@ The canonical store can contain several distinct asset classes:
 - `agents/`: role-specific agent manifests
 - `skills/`: workflow-specific capability folders
 - `mcp/`: canonical MCP server definitions
+- `mcp/servers.local.json` or `mcp/mcp.local.json`: ignored machine-local MCP secret overlay
 - `tools/<tool>/config.toml`: canonical tool config
+- `tools/<tool>/config.local.toml`: machine-local tool config overlay
 - `tools/<tool>/rules/*.rules`: canonical tool rules
 - global docs such as `AGENTS.global.md` and `AGENTS.override.global.md`
 
@@ -479,8 +481,13 @@ Built-ins currently include:
 Recommended split:
 - `~/.ai/config.toml` or `<repo>/.ai/config.toml`: tracked, portable, non-secret refs/defaults
 - `~/.ai/config.local.toml` or `<repo>/.ai/config.local.toml`: ignored, machine-local paths and secrets
+- `~/.ai/mcp/servers.json` or `<repo>/.ai/mcp/servers.json`: tracked canonical MCP definitions
+- `~/.ai/mcp/servers.local.json` or `<repo>/.ai/mcp/servers.local.json`: ignored machine-local MCP env overlay for secrets and per-machine auth
+- `~/.ai/tools/<tool>/config.toml` or `<repo>/.ai/tools/<tool>/config.toml`: tracked tool defaults
+- `~/.ai/tools/<tool>/config.local.toml` or `<repo>/.ai/tools/<tool>/config.local.toml`: ignored, machine-local tool overrides merged after tracked tool config during sync
 - `[builtin].sync_defaults = false`: disable builtin default sync/materialization for this root
 - `fclt sync --builtin-conflicts overwrite`: allow packaged builtin defaults to overwrite locally modified generated targets
+- `fclt audit fix ...`: move inline MCP secrets from tracked canonical config into the local MCP overlay and re-sync managed tool configs
 
 ### Snippets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.5.2",
+  "version": "2.7.0",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

package/src/audit/agent.ts

@@ -9,6 +9,10 @@ import {
   sanitizeCodexTomlMcpText,
 } from "../util/codex-toml";
 import { parseJsonLenient } from "../util/json";
+import {
+  applyAuditSuppressionsToAgentReport,
+  loadAuditSuppressions,
+} from "./suppressions";
 import {
   type AuditFinding,
   type AuditItemResult,
@@ -926,27 +930,7 @@ export async function runAgentAudit(opts?: {
     });
   }
 
-  // Summary
-  const bySeverity: Record<Severity, number> = {
-    low: 0,
-    medium: 0,
-    high: 0,
-    critical: 0,
-  };
-  let totalFindings = 0;
-  let flaggedItems = 0;
-
-  for (const r of results) {
-    totalFindings += r.findings.length;
-    if (!r.passed && r.findings.length > 0) {
-      flaggedItems += 1;
-    }
-    for (const f of r.findings) {
-      bySeverity[f.severity] += 1;
-    }
-  }
-
-  const report: AgentAuditReport = {
+  let report: AgentAuditReport = {
     timestamp: new Date().toISOString(),
     mode: "agent",
     agent: { tool, model },
@@ -972,12 +956,30 @@ export async function runAgentAudit(opts?: {
     }),
     summary: {
       totalItems: results.length,
-      totalFindings,
-      bySeverity,
-      flaggedItems,
+      totalFindings: results.reduce(
+        (sum, result) => sum + result.findings.length,
+        0
+      ),
+      bySeverity: results.reduce<Record<Severity, number>>(
+        (acc, result) => {
+          for (const finding of result.findings) {
+            acc[finding.severity] += 1;
+          }
+          return acc;
+        },
+        { low: 0, medium: 0, high: 0, critical: 0 }
+      ),
+      flaggedItems: results.filter(
+        (result) => !result.passed && result.findings.length > 0
+      ).length,
     },
   };
 
+  report = applyAuditSuppressionsToAgentReport(
+    report,
+    await loadAuditSuppressions(home)
+  );
+
   const auditDir = join(facultStateDir(home), "audit");
   await mkdir(auditDir, { recursive: true });
   await Bun.write(