@yaklabs-ai/plugin-sdk 0.12.3 → 0.12.5

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.12.3"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.12.5"
   }
 }
 ```
@@ -131,8 +131,10 @@ Pass the loader's inputs, not a subset — the audit judges what it is given:
   violations Kay itself would not report.
 
 `auditSkillCodegenPairs({ declaredSkills, exportedSkills, packageDir })` is the
-companion check for a bundled-skill plugin. Both are pure — they return
-violations rather than asserting — so any runner works. Both read from disk
+companion check for a bundled-skill plugin. It compares the decoded YAML
+`name` and `description` with the export, so quoting and block scalars are
+supported; body content must match after trimming surrounding whitespace.
+Both return violations rather than asserting, so any runner works. Both read from disk
 and call your own `help()`, so run them in Node, and keep `activate` free of
 side effects: the probe calls it.
 

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [
@@ -53,6 +53,13 @@
       "source": "https://github.com/colinhacks/zod",
       "note": "Installed as a consumer dependency; it is not bundled into the staged artifacts.",
       "versionRange": "^4.0.0"
+    },
+    {
+      "name": "yaml",
+      "license": "ISC",
+      "source": "https://github.com/eemeli/yaml",
+      "note": "Installed as a consumer dependency; it is not bundled into the staged artifacts.",
+      "versionRange": "^2.9.0"
     }
   ]
 }

package/dist/disclosure.d.ts

@@ -213,7 +213,8 @@ export declare interface AuditPluginDisclosureInput {
  * The codegen-pair equivalence check every bundled-skill plugin hand-rolled (see
  * `plugins/ARCHITECTURE.md` → "Bundled skills", step 4): every exported `PluginSkillDefinition`
  * must have a matching manifest declaration (same `localId`, same `description`), and the
- * declared `SKILL.md` file's frontmatter + body must match the export byte-for-byte.
+ * declared `SKILL.md` file's decoded YAML name and description must match the export.
+ * The body is compared byte-for-byte after trimming surrounding whitespace.
  */
 export declare function auditSkillCodegenPairs(input: AuditSkillCodegenPairsInput): Promise<readonly DisclosureViolation[]>;
 
@@ -1265,6 +1266,14 @@ declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * File I/O in user folders, run by the host on its own worker threads under a deadline and
+     * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
+     * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
+     * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
+     * {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link withJev}: there is nothing to
@@ -1569,6 +1578,135 @@ declare interface KayAppTimeSnapshot {
     readonly zoneSource: "host" | "utc-fallback";
 }
 
+declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
+ * its own worker threads.
+ *
+ * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
+ * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
+ * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
+ * which under a macOS-protected folder or on a drive that stopped answering can be a very long
+ * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
+ * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
+ * throwing.
+ *
+ * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
+ * exposes the same door without importing the `kay.app` surface.
+ */
+declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 declare type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
 
 declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";

package/dist/disclosure.js

@@ -1,5 +1,6 @@
 // packages/plugin-sdk/dist/disclosure/disclosure-conformance.js
 import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
 
 // packages/herd-uri/dist/connection.js
 var CONNECTION_SELECTOR_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)@([^/]+)(?:\/(.*))?$/;
@@ -700,24 +701,36 @@ async function auditSkillCodegenPairFile(skill, declaration, packageDir) {
     ];
   }
   const codegenPairMatch = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(file);
-  const frontmatter = codegenPairMatch?.[1] === void 0 ? void 0 : `${codegenPairMatch[1]}
-`;
+  const yaml = codegenPairMatch?.[1];
+  let frontmatter = {};
+  let parseError;
+  if (yaml !== void 0) {
+    try {
+      const parsed = parseYaml(yaml);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        frontmatter = parsed;
+      } else {
+        parseError = "frontmatter must be a YAML mapping";
+      }
+    } catch (error) {
+      parseError = errorMessage(error);
+    }
+  }
+  const parseDetail = parseError === void 0 ? "" : ` Could not parse '${declaration.path}': ${parseError}`;
   const body = codegenPairMatch?.[2];
   const violations = [];
-  if (frontmatter === void 0 || !frontmatter.includes(`name: ${skill.name}
-`)) {
+  if (frontmatter["name"] !== skill.name) {
     violations.push({
       moduleId: skill.name,
       rule: "skill-twin-frontmatter-name-mismatch",
-      detail: `SKILL.md frontmatter does not declare 'name: ${skill.name}'.`
+      detail: `SKILL.md frontmatter name does not match the exported name '${skill.name}'.${parseDetail}`
     });
   }
-  if (frontmatter === void 0 || !frontmatter.includes(`description: ${skill.description}
-`)) {
+  if (frontmatter["description"] !== skill.description) {
     violations.push({
       moduleId: skill.name,
       rule: "skill-twin-frontmatter-description-mismatch",
-      detail: "SKILL.md frontmatter description does not match the exported description."
+      detail: `SKILL.md frontmatter description does not match the exported description.${parseDetail}`
     });
   }
   if (body === void 0 || body.trim() !== skill.content.trim()) {
@@ -811,6 +824,17 @@ function createKayAgentProbeCapabilityHandles() {
     // real capability keeps for a zone the host cannot read.
     time: {
       snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
+    },
+    // Inert like the filesystem broker: a probe must never touch the user's disk.
+    userFiles: {
+      stat: inertResult,
+      readText: inertResult,
+      list: inertResult,
+      walk: inertResult,
+      realpath: inertResult,
+      writeText: inertResult,
+      mkdir: inertResult,
+      rename: inertResult
     }
   };
 }

package/dist/kay-agent-testing.d.ts

@@ -531,7 +531,7 @@ declare interface ExtensionPaths {
 export declare function fauxAuthContext(overrides?: Partial<ExtensionAuthContext>): ExtensionAuthContext;
 
 /** The capability handles a `KayAgentPluginApi` always carries — authority is decided per call. */
-export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time" | "userFiles">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
@@ -1167,6 +1167,14 @@ declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * File I/O in user folders, run by the host on its own worker threads under a deadline and
+     * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
+     * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
+     * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
+     * {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link withJev}: there is nothing to
@@ -1471,6 +1479,135 @@ declare interface KayAppTimeSnapshot {
     readonly zoneSource: "host" | "utc-fallback";
 }
 
+declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
+ * its own worker threads.
+ *
+ * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
+ * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
+ * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
+ * which under a macOS-protected folder or on a drive that stopped answering can be a very long
+ * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
+ * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
+ * throwing.
+ *
+ * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
+ * exposes the same door without importing the `kay.app` surface.
+ */
+declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 declare type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
 
 declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";

package/dist/kay-agent-testing.js

@@ -135,6 +135,16 @@ var UNWIRED_SURFACE = {
   screenshot: NOT_WIRED,
   open: NOT_WIRED
 };
+var USER_FILE_METHODS = [
+  "stat",
+  "readText",
+  "list",
+  "walk",
+  "realpath",
+  "writeText",
+  "mkdir",
+  "rename"
+];
 function fauxKayAgentCapabilities() {
   return {
     filesystem: {
@@ -191,7 +201,16 @@ function fauxKayAgentCapabilities() {
     // zone-of-record path overrides this handle after the spread.
     time: {
       snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
-    }
+    },
+    // Answers every call `error` naming itself, keeping the real contract's promise never to
+    // reject. A test that exercises a plugin's file I/O overrides this handle after the spread.
+    userFiles: Object.fromEntries(USER_FILE_METHODS.map((name) => [
+      name,
+      async () => ({
+        kind: "error",
+        detail: `userFiles.${name} is not wired in this test double`
+      })
+    ]))
   };
 }
 function defaultTestToolContext() {

package/dist/kay-agent.d.ts

@@ -1628,6 +1628,14 @@ export declare interface KayAgentPluginApi {
      * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * File I/O in user folders, run by the host on its own worker threads under a deadline and
+     * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
+     * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
+     * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
+     * {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link withJev}: there is nothing to
@@ -1946,6 +1954,135 @@ declare interface KayAppTimeSnapshot {
     readonly zoneSource: "host" | "utc-fallback";
 }
 
+export declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
+ * its own worker threads.
+ *
+ * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
+ * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
+ * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
+ * which under a macOS-protected folder or on a drive that stopped answering can be a very long
+ * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
+ * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
+ * throwing.
+ *
+ * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
+ * exposes the same door without importing the `kay.app` surface.
+ */
+export declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+export declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+export declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+export declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+export declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+export declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+export declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+export declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+export declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+export declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+export declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 declare const KayPluginManifestV1: z.ZodObject<{
     protocol: z.ZodLiteral<"kay.plugin.v1">;
     id: z.ZodString;

package/dist/kay-app.d.ts

@@ -2322,6 +2322,30 @@ export declare interface KayAppEndpoints {
     register(name: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
 }
 
+/**
+ * The plugin-facing `kay.app` repository contract: what git checkout encloses a folder, read by
+ * the host.
+ *
+ * Ungated and always present, like `app.paths`: a plugin runs in the daemon's process and could
+ * read these files itself. What `app.repos` adds is that the host reads them asynchronously, under
+ * a time limit, and shares one cache with the daemon. A plugin that reads `.git` files with
+ * `node:fs` sync calls blocks the daemon's event loop for as long as each read takes, which on a
+ * protected or unresponsive folder can be a very long time (kay#11575).
+ */
+/** One `[remote "<name>"]` in the repository's common `config`. */
+export declare interface KayAppGitRemote {
+    readonly name: string;
+    /** The `url =` value as written, still usable to connect. */
+    readonly url: string;
+    /**
+     * `url` reduced to a key that is the same however the repository is addressed: no scheme, user
+     * or port, lowercase host, no trailing `.git` (`git@github.com:org/repo.git` and
+     * `https://github.com/org/repo` are both `github.com/org/repo`). Absent when `url` reduces to
+     * nothing. For `owner/repo`, take the last two `/` segments.
+     */
+    readonly identity?: string;
+}
+
 /** A real human carrier projected into the source session's transcript. */
 export declare interface KayAppHumanMessageSessionEvent extends KayAppSessionEventBase {
     readonly type: "human-message";
@@ -2698,6 +2722,20 @@ export declare interface KayAppPluginApi {
      * `Intl` or `process.env.TZ`; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * Git facts about any folder (its checkout, primary checkout, common dir, remotes, and git's
+     * linked-worktree registry), read by the host asynchronously and under a time limit. Always
+     * present and ungated, like {@link paths}. Use it instead of reading `.git` files with `node:fs`,
+     * which blocks the daemon; see {@link KayAppRepos}.
+     */
+    readonly repos: KayAppRepos;
+    /**
+     * File I/O in user folders (stat, read, list, walk, realpath, write, mkdir, rename), run by the
+     * host on its own worker threads under a deadline and answered as a typed result. Always present
+     * and ungated, like {@link paths}. Use it instead of `node:fs`, whose sync calls block the
+     * daemon; see {@link KayAppUserFiles}.
+     */
+    readonly userFiles: KayAppUserFiles;
     /**
      * Read/arrange access to the live desktop workspace. Present whenever the host has a workspace
      * (a headless daemon may not); absence is a host fact, never a grant signal. Reading the snapshot
@@ -2872,6 +2910,102 @@ export declare interface KayAppRegisterUriModuleOptions {
     readonly scope: "app";
 }
 
+/** The git checkout that encloses a folder. Paths are absolute and not resolved through symlinks. */
+export declare interface KayAppRepoFacts {
+    /** The directory holding the `.git` entry: the nearest checkout at or above the folder. */
+    readonly repoRoot: string;
+    /**
+     * This checkout's own git directory: `<repoRoot>/.git`, or the target of a `.git` pointer file
+     * (a linked worktree or a submodule). `null` when the pointer could not be read.
+     */
+    readonly gitDir: string | null;
+    /**
+     * The git directory every worktree of the repository shares, as `git rev-parse
+     * --git-common-dir` names it; for a submodule, its own `.git/modules/<name>`. `null` when the
+     * host cannot place it (an unreadable pointer or `commondir` file).
+     */
+    readonly commonDir: string | null;
+    /**
+     * The primary checkout that owns a linked worktree; `repoRoot` itself for an ordinary
+     * checkout, a submodule, or a worktree of a bare repository. Every worktree of one repository
+     * shares this value.
+     */
+    readonly primaryCheckoutRoot: string;
+    /** A stable name for the repository: the primary checkout's directory name. */
+    readonly displayName: string;
+    /** Every remote in the common `config`, in file order. Empty when the config is unreadable. */
+    readonly remotes: readonly KayAppGitRemote[];
+    /**
+     * The `origin` remote. `absent` means the config was read and has no origin; `unavailable`
+     * means the config could not be read, which is not the same answer and is usually temporary.
+     */
+    readonly origin: {
+        readonly kind: "origin";
+        readonly url: string;
+        readonly identity: string;
+    } | {
+        readonly kind: "absent";
+    } | {
+        readonly kind: "unavailable";
+        readonly detail: string;
+    };
+}
+
+export declare interface KayAppRepoReadOptions {
+    /**
+     * How old a cached answer may be, in milliseconds. `0` asks the host to read again; `Infinity`
+     * accepts any cached answer. Default 5000.
+     */
+    readonly maxAgeMs?: number;
+}
+
+/** What the host knows about one folder. */
+export declare type KayAppRepoResolution = {
+    readonly kind: "resolved";
+    /** The folder asked about, as an absolute path. */
+    readonly folder: string;
+    /**
+     * Whether the folder itself exists. A folder that is gone still reports the checkout that
+     * encloses where it was, so a deleted subdirectory keeps its repository.
+     */
+    readonly folderExists: boolean;
+    /** `null` when no checkout encloses the folder. */
+    readonly repo: KayAppRepoFacts | null;
+} | {
+    /**
+     * The host could not answer: `timeout` when the reads took longer than the host's time limit
+     * (the folder may be on an unresponsive drive), `error` when they failed unexpectedly. Not
+     * cached, so asking again later may succeed. Treat it as "do not know", never as "no repo".
+     */
+    readonly kind: "unknown";
+    readonly folder: string;
+    readonly reason: "timeout" | "error";
+    readonly detail: string;
+};
+
+/**
+ * `app.repos`: git facts about folders, read by the host. Added in SDK 0.12.4: a plugin that calls
+ * it declares `compatibility.sdk` `^0.12.4`, so an older Bonsai refuses a directory or repository
+ * plugin at load instead of the call failing.
+ *
+ * Both members never reject and do not use `this`, so they are safe to destructure. Call them
+ * where you need the answer, not inside `activate()`.
+ */
+export declare interface KayAppRepos {
+    /**
+     * The checkout that encloses `folder` (an absolute path), or why the host could not tell. A
+     * relative path answers `unknown`.
+     */
+    readonly resolve: (folder: string, options?: KayAppRepoReadOptions) => Promise<KayAppRepoResolution>;
+    /**
+     * The working directories of the linked worktrees git has registered under `commonDir`
+     * (`<commonDir>/worktrees/<name>/gitdir`), including ones whose directory has since been
+     * deleted. Empty when there are none; `undefined` when the registry or one of its entries could
+     * not be read, or not in time. `undefined` is not cached; treat it as "do not know".
+     */
+    readonly linkedWorktrees: (commonDir: string, options?: KayAppRepoReadOptions) => Promise<readonly string[] | undefined>;
+}
+
 /** What the plugin is asking for, and what it intends to do with it. */
 export declare interface KayAppResolveCredentialRequest {
     /** An auth service this plugin's own manifest declares, by its LOCAL id. */
@@ -4097,6 +4231,135 @@ export declare interface KayAppUiActionSessionEvent extends KayAppSessionEventBa
     readonly toolCallId: string;
 }
 
+export declare interface KayAppUserFileEntry {
+    readonly name: string;
+    /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
+    readonly kind: KayAppUserFileKind;
+}
+
+/**
+ * The plugin-facing user-files contract: file I/O in folders the user owns, done by the host on
+ * its own worker threads.
+ *
+ * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
+ * daemon's process and can call `node:fs` itself. What the door adds is where the work runs. A
+ * `node:fs` sync call blocks the daemon's event loop for as long as the path takes to answer,
+ * which under a macOS-protected folder or on a drive that stopped answering can be a very long
+ * time (kay#11575); an async one holds a thread of the pool the whole daemon shares. The host runs
+ * each request on a dedicated worker, gives it a deadline, and answers a typed result instead of
+ * throwing.
+ *
+ * This is a leaf module. It lives beside both target SDKs, like `time.ts`, so the `kay.agent` SDK
+ * exposes the same door without importing the `kay.app` surface.
+ */
+export declare type KayAppUserFileKind = "file" | "directory" | "symlink" | "other";
+
+export declare interface KayAppUserFileListing {
+    readonly entries: readonly KayAppUserFileEntry[];
+    /** True when the directory had more entries than `maxEntries`; the rest were not read. */
+    readonly entryLimitReached: boolean;
+}
+
+/**
+ * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
+ * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
+ * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+export declare interface KayAppUserFiles {
+    /** Follows symlinks. */
+    stat(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<KayAppUserFileStat>>;
+    /** UTF-8. */
+    readText(path: string, options?: KayAppUserFilesReadTextOptions): Promise<KayAppUserFilesResult<string>>;
+    list(path: string, options?: KayAppUserFilesListOptions): Promise<KayAppUserFilesResult<KayAppUserFileListing>>;
+    /** Depth-first below `path`; symlinks are reported, never followed. */
+    walk(path: string, options?: KayAppUserFilesWalkOptions): Promise<KayAppUserFilesResult<KayAppUserFileWalk>>;
+    /** The path with every symlink resolved. */
+    realpath(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<string>>;
+    /**
+     * Creates or replaces a UTF-8 file, not atomically. After `timeout` or `aborted` the write may
+     * still happen.
+     */
+    writeText(path: string, content: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    /** Creates the directory and any missing parents; succeeds when it already exists. */
+    mkdir(path: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+    rename(from: string, to: string, options?: KayAppUserFilesCallOptions): Promise<KayAppUserFilesResult<null>>;
+}
+
+export declare interface KayAppUserFilesCallOptions {
+    /** Deadline in milliseconds from the call, waiting included. Default 5000, at most 60000. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+
+export declare interface KayAppUserFilesListOptions extends KayAppUserFilesCallOptions {
+    /** Default 5000, at most 50000. */
+    readonly maxEntries?: number;
+}
+
+export declare interface KayAppUserFilesReadTextOptions extends KayAppUserFilesCallOptions {
+    /** A larger file answers `error` with code `EFBIG`. Default 8 MiB, at most 64 MiB. */
+    readonly maxBytes?: number;
+}
+
+/**
+ * Every answer. `missing`: nothing exists at the path (ENOENT). `timeout`: no answer from the path
+ * in time. Its `reason` is `deadline` (this request ran out of time), `cooling-down` (a request at
+ * or above this path timed out recently, so the host did not try) or `saturated` (the host's
+ * workers are stuck on other paths, so it did not try). `aborted`: the caller's signal fired.
+ * `error`: anything else, with the Node error `code` when there is one (`EACCES`, `EISDIR`,
+ * `EFBIG` for a file over `maxBytes`, `EINVAL` for a relative path).
+ */
+export declare type KayAppUserFilesResult<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "timeout";
+    readonly reason: "deadline" | "cooling-down" | "saturated";
+    readonly detail: string;
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "error";
+    readonly code?: string;
+    readonly detail: string;
+};
+
+export declare interface KayAppUserFileStat {
+    /** What the path is after following symlinks; never `symlink`. */
+    readonly kind: "file" | "directory" | "other";
+    /** Bytes. */
+    readonly size: number;
+    /** Milliseconds since the Unix epoch. */
+    readonly modifiedAtMs: number;
+}
+
+export declare interface KayAppUserFilesWalkOptions extends KayAppUserFilesCallOptions {
+    /** Default 10000, at most 100000. */
+    readonly maxEntries?: number;
+    /** Deepest level reported; the root's children are depth 1. Default 16, at most 64. */
+    readonly maxDepth?: number;
+    /** Report and descend into dot-prefixed entries. Default true. */
+    readonly includeHidden?: boolean;
+}
+
+export declare interface KayAppUserFileWalk {
+    readonly entries: readonly KayAppUserFileWalkEntry[];
+    /** True when the walk stopped at `maxEntries`. */
+    readonly entryLimitReached: boolean;
+    /** True when a directory at `maxDepth` was reported but not descended into. */
+    readonly depthLimitReached: boolean;
+}
+
+export declare interface KayAppUserFileWalkEntry {
+    /** Path segments below the walk's root. */
+    readonly segments: readonly string[];
+    readonly kind: KayAppUserFileKind;
+}
+
 export declare interface KayAppWhiteboard {
     /**
      * Binds read-only Whiteboard access to the exact context issued to this plugin's session source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -51,7 +51,8 @@
     "skills"
   ],
   "dependencies": {
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "yaml": "^2.9.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/skills/directory-plugin-authoring/SKILL.md

@@ -55,6 +55,31 @@ and symlinking `node_modules/@kay` into the copy does not rescue it either: pnpm
 layout does not expose workspace packages that way. The scaffold exists precisely so this
 cannot happen.
 
+## Check the manifest before you wait for a load
+
+```
+pnpm plugin:check ~/.kay/plugins/widgets
+```
+
+Run from the root of a Kay checkout, against the plugin directory. It runs the daemon's OWN
+manifest schema and contract resolver (imported from `@kay/plugin-protocol`, not re-implemented),
+so it answers "would Kay accept this manifest?" in about a second instead of after a load cycle.
+Run it after every manifest edit, and before concluding a plugin is broken for some deeper reason.
+
+It prints the resolved global contribution ids, exits non-zero when the plugin would be refused,
+and separates the two outcomes that look alike from outside:
+
+- **Refused outright** — schema-invalid manifest, a reserved `kay.*` / `herd.*` id, a declared
+  path escaping the plugin directory, or contributions that do not resolve. Every contribution
+  shares ONE flat `<namespace>.<localId>` space ACROSS kinds, so a tool and an endpoint both
+  called `inspect` collide and the whole plugin is refused (#8936).
+- **Loads, minus something** — a retired `compatibility` / `permissions.byTarget` key the parser
+  strips silently, a `toolName` that is not the namespace-derived name (that tool is excluded and
+  nothing tells the user), a missing entrypoint or skill file.
+
+It reads the manifest only. A clean verdict says nothing about `activate()` throwing, the
+disclosure audit, or an id another installed plugin already claims.
+
 ## The SDK resolution contract
 
 - Plugin source imports `@kay/plugin-sdk/<subpath>` as a **bare specifier**
@@ -123,8 +148,10 @@ edited.
    IS a git repository: a version is a commit, and a directory without git backing fails to
    load (the plugin's row says exactly that, with the fix). So after writing the files, commit
    them: `git init && git add -A && git commit -m "adopt plugin"` inside the plugin directory.
-   The daemon watches the root, so the plugin appears by itself within a couple of seconds, no
-   verb called and no restart; the source refresh verb forces the walk if you want it now.
+   The daemon watches the root and, under the watch, checks each plugin's Git HEAD every 5
+   seconds, so it notices the plugin by itself within about 10 seconds even when file events
+   are not arriving: no verb called and no restart. The source refresh verb forces the walk if
+   you want it now.
 
    The root is `<home>/.kay/plugins`, and **`<home>` is the running instance's home**: a dev
    app launched against its own state root has its own plugins root, not your real
@@ -144,9 +171,13 @@ list` names the exact local root — because writing into the wrong one produces
    commit** identifies the serving snapshot. Try new tools in a fresh session;
    an existing session may still hold its previous generation.
 
-   A failed committed update keeps the last working revision and shows the load
-   diagnostic. Fix and commit the repair. Explicit source refresh retries discovery
-   or a failed read; it never activates uncommitted files. Keep runtime data in
+   Kay notices a commit within about 10 seconds even with no file events, and acquiring it may
+   take up to 30 seconds more. A **Running commit** still behind `git rev-parse --short HEAD` a
+   minute later, with a diagnostic on the plugin's row, is a failed read: fix what it names
+   instead of refreshing and waiting. Without a diagnostic, refresh the `local` source. A failed committed
+   update keeps the last working revision and shows that diagnostic. Fix and commit the
+   repair. Explicit source refresh skips the wait and retries a failed read; a commit
+   does not normally need it, and it never activates uncommitted files. Keep runtime data in
    host-owned plugin storage, not beside the snapshot's source files.
 
 4. **Grant what the manifest asks for, or activation is refused.** Anything declared under
@@ -177,9 +208,10 @@ list` names the exact local root — because writing into the wrong one produces
 The commit is the activation boundary, so run these against the working tree first. Each catches
 a failure class the load would otherwise be the first thing to surface:
 
-1. **Validate `kay-plugin.json` against `KayPluginManifestV1`** (from `@kay/plugin-protocol`),
-   not just "it is valid JSON" — that schema is the gate the scan actually runs. Check every
-   declared target's endpoints are namespaced correctly.
+1. **Run `pnpm plugin:check <dir>`** from a Kay checkout. It validates `kay-plugin.json` against
+   `KayPluginManifestV1` and resolves its contributions with the daemon's own resolver (both from
+   `@kay/plugin-protocol`), not just "it is valid JSON": that schema and resolver are the gate the
+   scan actually runs. A non-zero exit means the plugin would be refused.
 2. **Run the disclosure audit yourself**: `auditPluginDisclosure` from `@kay/plugin-sdk/disclosure`.
    It is not redundant with typecheck. A plugin shipped a `search` verb with no `verbDocs` entry
    that typechecked clean and would have failed the whole `kay.agent` target.
@@ -229,6 +261,8 @@ on the plugin's row (or on the plugin source's row, when the whole source found
 - **The disclosure audit is fail-closed** and runs on every directory plugin; a violation fails
   the whole `kay.agent` target. Run `auditPluginDisclosure` yourself before committing, per the
   pre-commit checks above.
+- **Before any of the above, run `pnpm plugin:check <dir>`.** A manifest the daemon cannot
+  resolve produces a plugin that never appears, and the check names the reason without a load.
 
 ## Declaring a scheduled workflow