@lifeaitools/clauth 1.30.17 → 1.30.18

package/cli/supervisor-registry.js

@@ -13,6 +13,7 @@ const ACTIONS = new Set(["start", "stop", "restart", "reconcile", "test", "promo
 const DEFAULT_HEALTH_RECONCILE_INTERVAL_MS = 10000;
 const DEFAULT_HEALTH_TIMEOUT_MS = 2500;
 const HEALTH_RECONCILE_COOLDOWN_MS = 15000;
+const DOCUMENTATION_FIELDS = ["architecture", "operator_guide", "install", "runbook", "tool_reference", "release", "agent_context"];
 
 export function getSupervisorPort() {
   return Number(process.env.CLAUTH_SUPERVISOR_PORT || DEFAULT_SUPERVISOR_PORT);
@@ -188,6 +189,25 @@ function normalizeDestination(destination) {
   return value;
 }
 
+function normalizeDocumentation(value) {
+  if (value == null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("documentation must be an object");
+  const documentation = {};
+  for (const field of DOCUMENTATION_FIELDS) {
+    if (value[field] == null) continue;
+    if (typeof value[field] !== "string" || !value[field].trim()) {
+      throw new Error(`documentation.${field} must be a non-empty path`);
+    }
+    const ref = value[field].trim().replaceAll("\\", "/");
+    if (ref.startsWith("/") || ref.includes("..") || /^[a-z]+:/i.test(ref)) {
+      throw new Error(`documentation.${field} must be a repository-relative path`);
+    }
+    documentation[field] = ref;
+  }
+  if (!documentation.architecture) throw new Error("documentation.architecture is required");
+  return documentation;
+}
+
 function localhostHealth(pathOrUrl, port) {
   if (!pathOrUrl) return null;
   if (/^https?:\/\//i.test(pathOrUrl)) {
@@ -237,6 +257,7 @@ export function validatePluginManifest(manifest, sourcePath = "") {
     id,
     version,
     publisher: String(manifest.publisher || "unknown"),
+    documentation: normalizeDocumentation(manifest.documentation),
     // Only trusted managed manifests may opt into automatic startup. User
     // plugins remain awaiting_enable until an operator explicitly enables them.
     core: manifest.core === true,

package/cli/supervisor-registry.test.js

@@ -66,6 +66,11 @@ function baseManifest(id, overrides = {}) {
       restart: ["node", "--version"],
     }],
     test: { command: ["node", "--version"], port: "auto", health: "/health", selfTest: [["node", "--version"]] },
+    documentation: {
+      architecture: "docs/systems/example/ARCHITECTURE.md",
+      operator_guide: "docs/systems/example/OPERATE.md",
+      tool_reference: ".claude/context/mcp-endpoint-design.md",
+    },
     ...overrides,
   };
 }
@@ -77,6 +82,8 @@ test("validatePluginManifest accepts LIFEAI plugin contract with isolated test c
   assert.equal(plugin.surfaces[0].destination, "local/clauth/pm2");
   assert.equal(plugin.surfaces[0].lifecycle_owner, "clauth");
   assert.equal(plugin.surfaces[0].health, "http://127.0.0.1:39111/health");
+  assert.equal(plugin.documentation.architecture, "docs/systems/example/ARCHITECTURE.md");
+  assert.equal(plugin.documentation.operator_guide, "docs/systems/example/OPERATE.md");
 });
 
 test("validatePluginManifest accepts empty test command arrays from the v1 template", () => {
@@ -92,6 +99,15 @@ test("validatePluginManifest rejects invalid manifests and non-local health URLs
   assert.throws(() => validatePluginManifest(baseManifest("bad", {
     surfaces: [{ id: "bad", health: "https://example.com/health" }],
   })), /localhost-only/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { architecture: "../outside.md" },
+  })), /repository-relative/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { operator_guide: "docs/guide.md" },
+  })), /documentation.architecture is required/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { architecture: "https://example.com/architecture.md" },
+  })), /repository-relative/);
 });
 
 test("discovery merges managed and user roots without silent managed-id shadowing", () => withTempSupervisor((root) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/clauth",
-  "version": "1.30.17",
+  "version": "1.30.18",
   "description": "Hardware-bound credential vault for the LIFEAI infrastructure stack",
   "type": "module",
   "bin": {