@yaklabs-ai/plugin-sdk 0.12.5 → 0.13.1

package/dist/kay-app.js

@@ -105,6 +105,9 @@ var RUN_ID = /^\P{Cc}+$/u;
 var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
 var ObserveShape = z.looseObject({
   detector: z.looseObject({ id: z.string(), version: z.string() }),
+  subject: z.looseObject({ kind: z.string(), key: z.string().optional() }).optional(),
+  after: z.looseObject({ observationId: z.unknown() }).optional(),
+  reuse: z.looseObject({ maxAgeMs: z.unknown() }).optional(),
   source: z.looseObject({
     sessionId: z.string(),
     entryId: z.string(),
@@ -119,6 +122,7 @@ var ChoiceQuestion = z.looseObject({
   criteria: z.record(z.string(), z.unknown())
 });
 var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
+var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
 var quoted = (value) => JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}\u2026` : value).replace(/(?! )[\s\p{C}]/gu, (char) => `\\u${char.codePointAt(0).toString(16).padStart(4, "0")}`);
 function grammarProblem(input) {
   const shape = ObserveShape.safeParse(input);
@@ -126,7 +130,7 @@ function grammarProblem(input) {
     const field = shape.error.issues[0]?.path.join(".") ?? "";
     return field === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field}\` is missing or has the wrong type.`;
   }
-  const { detector, source, questions } = shape.data;
+  const { detector, source, questions, subject, after, reuse } = shape.data;
   const { state } = input;
   if (typeof state !== "object" || state === null || Array.isArray(state)) {
     return "`state` must be a JSON object.";
@@ -156,6 +160,23 @@ function grammarProblem(input) {
   if (occurredAtMs !== void 0 && !(typeof occurredAtMs === "number" && Number.isSafeInteger(occurredAtMs) && occurredAtMs >= 0 && occurredAtMs <= SIGNAL_TIME_MAX_MS)) {
     return `\`source.occurredAtMs\` must be whole epoch milliseconds from 0 to ${SIGNAL_TIME_MAX_MS}.`;
   }
+  if (subject !== void 0 && !fits(subject.kind, DETECTOR_ID)) {
+    return "`subject.kind` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
+  }
+  if (subject?.key !== void 0 && !(subject.key.length <= MAX_POINTER && POINTER.test(subject.key))) {
+    return `\`subject.key\` must be ${POINTER_RULE}.`;
+  }
+  if (after !== void 0 && !isWhole(after.observationId, 1)) {
+    return "`after.observationId` must be a positive whole number: the id of a stored signal.";
+  }
+  if (reuse !== void 0) {
+    if (!isWhole(reuse.maxAgeMs, 1)) {
+      return `\`reuse.maxAgeMs\` must be whole milliseconds from 1 to ${SIGNAL_TIME_MAX_MS}.`;
+    }
+    if (subject?.key === void 0) {
+      return "`reuse` needs `subject.key`: a stored answer is reused only for the same subject.";
+    }
+  }
   const names = Object.keys(questions);
   if (names.length === 0 || names.length > MAX_QUESTIONS) {
     return `\`questions\` must ask 1 to ${MAX_QUESTIONS} questions.`;

package/dist/signals.d.ts

@@ -7,6 +7,9 @@
  */
 export declare function createFallbackOnlySignals(): KayAppSignals;
 
+/** The engine over one plugin's `observe` (normally `app.signals.observe`). */
+export declare function createSignalEngine(observe: KayAppSignals["observe"]): SignalEngine;
+
 /**
  * The `invalid` observation `observe` answers when a name in `input` breaks the recorded-name
  * grammar, or `undefined` when every name can be recorded. A reader later types these names into
@@ -86,7 +89,7 @@ declare interface JevScoreQuestion {
  *     Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
  * ---
  *
- * The vocabulary is Kay's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
+ * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
  * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
  * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
  * criterion is text, and the state is a JSON object.
@@ -106,6 +109,10 @@ export declare interface KayAppSignal {
         readonly pluginId: string;
     };
     readonly source: KayAppSignalSource;
+    /** What the signal is about, when its recorder named a subject. */
+    readonly subject?: KayAppSignalSubject;
+    /** The id of the upstream signal this one was chained after, while that row exists. */
+    readonly upstreamId?: number;
     readonly recordedAtMs: number;
     /** Keyed by question name, full probability distributions included. */
     readonly answers: Readonly<Record<string, KayAppSignalAnswer>>;
@@ -165,12 +172,20 @@ export declare interface KayAppSignalNoulAnswer {
  *
  * A repeat call over the same (plugin, detector, version, session, entry, input digest) returns
  * the ALREADY-STORED row with `deduplicated: true` and never calls Jev again: replay is free.
+ * A call with `reuse` that finds a recent row for the same subject key returns that row with
+ * `deduplicated: true` and `reused: true`; its `source` is where the row was computed.
  */
 export declare interface KayAppSignalObservation {
     readonly id?: number | undefined;
     readonly status: "classified" | "unavailable" | "invalid";
     readonly detector: KayAppSignalsDetectorRef;
     readonly source: KayAppSignalSource;
+    /** The row's subject, when it was recorded with one. */
+    readonly subject?: KayAppSignalSubject | undefined;
+    /** The row's upstream link: the id of the row it was chained after. */
+    readonly upstreamId?: number | undefined;
+    /** True when the answer is a stored row found through `reuse`, not this call's own. */
+    readonly reused?: boolean | undefined;
     readonly answers?: Record<string, unknown> | undefined;
     readonly model?: string | undefined;
     readonly usage?: {
@@ -203,6 +218,18 @@ export declare interface KayAppSignalPage {
     readonly nextCursor?: string;
 }
 
+/**
+ * Reuse a stored answer for the same subject instead of asking Jev again. Before any Jev call
+ * the host looks for the newest row this plugin recorded with the same detector, version,
+ * subject key and input digest, recorded at most `maxAgeMs` ago, in ANY session. When one
+ * exists, that row is the answer: no Jev call and no new row. The returned observation keeps the
+ * row's own source (where it was computed), with `reused: true`.
+ */
+export declare interface KayAppSignalReuse {
+    /** How old a stored answer may be, in ms: a whole number from 1 to {@link SIGNAL_TIME_MAX_MS}. */
+    readonly maxAgeMs: number;
+}
+
 /**
  * One question of a stored rubric, as the recording plugin wrote it. Rubrics recorded before
  * SDK 0.12.0 use TypeSafe's vocabulary (`noul` for yes/no, and instructions or criteria that
@@ -331,6 +358,12 @@ export declare interface KayAppSignalsDetectorRef extends KayAppSignalsDetectorI
 export declare interface KayAppSignalsObserveInput {
     readonly detector: KayAppSignalsDetectorInput;
     readonly source: KayAppSignalSource;
+    /** What the signal is about. Stored on the row; not part of the dedupe key or the input digest. */
+    readonly subject?: KayAppSignalSubject;
+    /** The upstream row this observation is chained after. Stored on the row as its upstream link. */
+    readonly after?: KayAppSignalUpstreamLink;
+    /** Reuse a recent stored answer for the same subject key. Needs `subject.key`. */
+    readonly reuse?: KayAppSignalReuse;
     /**
      * The exact state to send, already shaped by the caller (a turn packet, a window of messages,
      * or anything else). NOT stored: the row keeps its digest, and a reader re-derives it from the
@@ -428,6 +461,34 @@ export declare interface KayAppSignalsSessionQuery {
     readonly limit?: number;
 }
 
+/**
+ * What a signal is about, named by the recording plugin. The host stores both values and never
+ * interprets them. A signal recorded without a subject has none; every reader treats it as before.
+ */
+export declare interface KayAppSignalSubject {
+    /**
+     * The kind of thing observed, e.g. `turn`: a lowercase slug of at most 64 characters, in the
+     * same grammar as a detector id.
+     */
+    readonly kind: string;
+    /**
+     * The subject's identity ACROSS sessions, when it has one (two sessions can observe the same
+     * subject). Required for {@link KayAppSignalsObserveInput.reuse}. 1 to 256 characters with no
+     * whitespace, `/`, `?`, `#`, or control or invisible character.
+     */
+    readonly key?: string;
+}
+
+/**
+ * The upstream signal a chained observation ran after: the stored row whose answers the caller
+ * found passing. The host checks that the row exists and was recorded by the same plugin, and
+ * stores the link on the new row; it never re-judges the caller's pass condition.
+ */
+export declare interface KayAppSignalUpstreamLink {
+    /** The upstream row's `id`: a positive whole number. */
+    readonly observationId: number;
+}
+
 /** The most labels a recorded choice question may offer, and so the most one filter names. */
 export declare const MAX_CHOICE_LABELS = 64;
 
@@ -437,6 +498,119 @@ export declare const MAX_CHOICE_LABELS = 64;
  */
 export declare const SIGNAL_TIME_MAX_MS = 8640000000000000;
 
+/**
+ * Whether stored answers satisfy every filter, with the store's own semantics: a yes/no
+ * question's P(yes) (`bool`'s `probability`, or `noul` in older rows), a choice question's label
+ * and confidence, a score question's expected score. An answer of another kind, a missing answer
+ * or a malformed one never passes. No filters always pass.
+ */
+export declare function signalAnswersPass(answers: Readonly<Record<string, unknown>> | undefined, filters: readonly KayAppSignalsAnswerFilter[]): boolean;
+
+/**
+ * One Jev signal a plugin records, over subjects of type `I`. `id`, `version` and `questions`
+ * are exactly what `observe` records under; `subjectKind` is stored on every row.
+ */
+export declare interface SignalDefinition<I> {
+    /** The detector id rows are recorded under (a lowercase slug, at most 64 characters). */
+    readonly id: string;
+    /** Bump it when a question changes meaning. */
+    readonly version: string;
+    /** What this signal is about, e.g. `turn`: a lowercase slug, stored on the row. */
+    readonly subjectKind: string;
+    readonly questions: JevQuestions;
+    /**
+     * The state Jev reads for this subject, or `undefined` when the subject carries nothing this
+     * signal can judge (no row is recorded). Must be a pure function of the subject: the row keeps
+     * only its digest.
+     */
+    readonly project: (input: I) => JevState | undefined;
+    /**
+     * The subject's identity across sessions. Required with `maxAgeMs`; without it a row is tied
+     * to its own anchor only.
+     */
+    readonly key?: (input: I) => string;
+    /**
+     * Reuse a stored answer for the same subject key and state for this long, in ms, in any
+     * session, instead of asking Jev again. Expiry belongs to the definition.
+     */
+    readonly maxAgeMs?: number;
+    /** The upstream signal that must pass before this one is evaluated. */
+    readonly after?: SignalUpstream<I>;
+}
+
+/**
+ * `sha256:<hex>` over a value serialised with sorted object keys, so two payloads that differ
+ * only in key order digest the same. The host stamps both digests a row carries with it: the
+ * input digest (the dedupe member of the natural key) and the rubric digest (the versioning
+ * tripwire). A caller may compute it too, to name a state without keeping it.
+ *
+ * The value is normalised THROUGH `JSON.stringify` first, deliberately. The digest must
+ * describe what the vendor actually received, and the vendor receives JSON: a `Date` goes over
+ * the wire as its ISO string, an `undefined` array slot as `null`, an `undefined` object value
+ * not at all. Canonicalising the raw JS value instead let two genuinely different states digest
+ * the same (`[]` and `[undefined]`; `{}` and any `Date`), and since the digest is a member of
+ * the store's natural key, a collision is not a crash but SILENT EVIDENCE LOSS: the second
+ * state dedupes against the first and is never observed. A value JSON cannot represent (a
+ * bigint) throws.
+ */
+export declare function signalDigest(value: unknown): string;
+
+export declare interface SignalEngine {
+    /**
+     * Evaluate each definition over one subject, in order, and return one result per definition.
+     * `source` anchors every row to the transcript; `options` is passed to every observe, with
+     * `purpose` set to `signals/<id>`.
+     */
+    evaluate<I>(definitions: readonly SignalDefinition<I>[], input: I, source: KayAppSignalSource, options?: WithJevOptions): Promise<readonly SignalEvaluation[]>;
+}
+
+/**
+ * What evaluating one definition produced:
+ *
+ * - `observed`: `observe` returned; read `observation.status` (an unavailable or invalid outcome
+ *   is still `observed`: the engine reports what the host answered).
+ * - `skipped`: the projection returned `undefined`; nothing was observed.
+ * - `blocked`: the upstream did not pass (or the subject has none); `upstream` is its result,
+ *   absent when `find` named no upstream subject.
+ * - `failed`: the projection, `find`, `key` or `observe` threw.
+ */
+export declare type SignalEvaluation = {
+    readonly kind: "observed";
+    readonly signal: SignalRef;
+    readonly observation: KayAppSignalObservation;
+} | {
+    readonly kind: "skipped";
+    readonly signal: SignalRef;
+} | {
+    readonly kind: "blocked";
+    readonly signal: SignalRef;
+    readonly upstream?: SignalEvaluation;
+} | {
+    readonly kind: "failed";
+    readonly signal: SignalRef;
+    readonly error: unknown;
+};
+
+/** The signal a result is about. */
+declare interface SignalRef {
+    readonly id: string;
+    readonly version: string;
+}
+
+/**
+ * The upstream a chained signal runs after. `find` names the upstream subject (and where it sits
+ * in the transcript) for a downstream subject, or `undefined` when it has none, which blocks the
+ * downstream. `pass` uses the same filters a signals read uses; every one must hold.
+ */
+export declare interface SignalUpstream<I> {
+    readonly signal: SignalDefinition<never>;
+    readonly find: (input: I, source: KayAppSignalSource) => {
+        readonly input: unknown;
+        readonly source: KayAppSignalSource;
+    } | undefined;
+    readonly pass: readonly KayAppSignalsAnswerFilter[];
+}
+
 /** Per-call knobs for {@link WithJev}. Every field is optional; the host applies its own default
  *  budget when none is given, so the Jev branch is never unbounded. */
 declare interface WithJevOptions {

package/dist/signals.js

@@ -1,5 +1,120 @@
 // packages/plugin-sdk/dist/signals.js
 import { z } from "zod";
+
+// packages/plugin-sdk/dist/signal-digest.js
+import { createHash } from "node:crypto";
+function signalDigest(value) {
+  const json = JSON.stringify(value);
+  const normalised = json === void 0 ? null : JSON.parse(json);
+  return `sha256:${createHash("sha256").update(canonicalJson(normalised)).digest("hex")}`;
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value;
+    return `{${Object.keys(record).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(record[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+// packages/plugin-sdk/dist/signal-engine.js
+var MAX_CHAIN_DEPTH = 16;
+function createSignalEngine(observe) {
+  return {
+    async evaluate(definitions, input, source, options) {
+      const memo = /* @__PURE__ */ new Map();
+      const run = async (definition, subject, at, chain) => {
+        const signal = { id: definition.id, version: definition.version };
+        try {
+          const state = definition.project(subject);
+          if (state === void 0)
+            return { kind: "skipped", signal };
+          const key = definition.key?.(subject);
+          const memoKey = JSON.stringify([
+            definition.id,
+            definition.version,
+            at.sessionId,
+            at.entryId,
+            key ?? null,
+            signalDigest(state)
+          ]);
+          if (chain.includes(memoKey)) {
+            throw new Error(`signal '${definition.id}' is chained after itself`);
+          }
+          if (chain.length >= MAX_CHAIN_DEPTH) {
+            throw new Error(`signal '${definition.id}' is chained more than ${MAX_CHAIN_DEPTH} deep`);
+          }
+          const known = memo.get(memoKey);
+          if (known !== void 0)
+            return await known;
+          const pending = observeOne(definition, signal, subject, at, state, key, [...chain, memoKey]);
+          memo.set(memoKey, pending);
+          return await pending;
+        } catch (error) {
+          return { kind: "failed", signal, error };
+        }
+      };
+      const observeOne = async (definition, signal, subject, at, state, key, chain) => {
+        try {
+          let upstreamId;
+          if (definition.after !== void 0) {
+            const found = definition.after.find(subject, at);
+            if (found === void 0)
+              return { kind: "blocked", signal };
+            const upstream = await run(definition.after.signal, found.input, found.source, chain);
+            if (upstream.kind !== "observed" || upstream.observation.status !== "classified" || upstream.observation.id === void 0 || !signalAnswersPass(upstream.observation.answers, definition.after.pass)) {
+              return { kind: "blocked", signal, upstream };
+            }
+            upstreamId = upstream.observation.id;
+          }
+          const observation = await observe({
+            detector: signal,
+            source: at,
+            subject: {
+              kind: definition.subjectKind,
+              ...key === void 0 ? {} : { key }
+            },
+            ...upstreamId === void 0 ? {} : { after: { observationId: upstreamId } },
+            ...definition.maxAgeMs === void 0 ? {} : { reuse: { maxAgeMs: definition.maxAgeMs } },
+            state,
+            questions: definition.questions,
+            options: { ...options, purpose: `signals/${definition.id}` }
+          });
+          return { kind: "observed", signal, observation };
+        } catch (error) {
+          return { kind: "failed", signal, error };
+        }
+      };
+      const results = [];
+      for (const definition of definitions) {
+        const result = await run(definition, input, source, []);
+        results.push(result);
+      }
+      return results;
+    }
+  };
+}
+function signalAnswersPass(answers, filters) {
+  return filters.every((filter) => {
+    const answer = answers?.[filter.question];
+    if (typeof answer !== "object" || answer === null)
+      return false;
+    const record = answer;
+    const within = (value, range) => typeof value === "number" && (range.atLeast === void 0 || value >= range.atLeast) && (range.atMost === void 0 || value <= range.atMost);
+    if ("yes" in filter) {
+      const value = record["type"] === "bool" ? record["probability"] : record["type"] === "noul" ? record["noul"] : void 0;
+      return within(value, filter.yes);
+    }
+    if ("choice" in filter) {
+      return record["type"] === "choice" && typeof record["choice"] === "string" && filter.choice.includes(record["choice"]) && within(record["confidence"], { atLeast: filter.minConfidence ?? 0 });
+    }
+    return record["type"] === "score" && within(record["score"], filter.score);
+  });
+}
+
+// packages/plugin-sdk/dist/signals.js
 function createFallbackOnlySignals() {
   const noStore = { status: "unavailable", reason: "no-store" };
   return {
@@ -31,6 +146,9 @@ var RUN_ID = /^\P{Cc}+$/u;
 var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
 var ObserveShape = z.looseObject({
   detector: z.looseObject({ id: z.string(), version: z.string() }),
+  subject: z.looseObject({ kind: z.string(), key: z.string().optional() }).optional(),
+  after: z.looseObject({ observationId: z.unknown() }).optional(),
+  reuse: z.looseObject({ maxAgeMs: z.unknown() }).optional(),
   source: z.looseObject({
     sessionId: z.string(),
     entryId: z.string(),
@@ -45,6 +163,7 @@ var ChoiceQuestion = z.looseObject({
   criteria: z.record(z.string(), z.unknown())
 });
 var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
+var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
 var quoted = (value) => JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}\u2026` : value).replace(/(?! )[\s\p{C}]/gu, (char) => `\\u${char.codePointAt(0).toString(16).padStart(4, "0")}`);
 function grammarProblem(input) {
   const shape = ObserveShape.safeParse(input);
@@ -52,7 +171,7 @@ function grammarProblem(input) {
     const field = shape.error.issues[0]?.path.join(".") ?? "";
     return field === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field}\` is missing or has the wrong type.`;
   }
-  const { detector, source, questions } = shape.data;
+  const { detector, source, questions, subject, after, reuse } = shape.data;
   const { state } = input;
   if (typeof state !== "object" || state === null || Array.isArray(state)) {
     return "`state` must be a JSON object.";
@@ -82,6 +201,23 @@ function grammarProblem(input) {
   if (occurredAtMs !== void 0 && !(typeof occurredAtMs === "number" && Number.isSafeInteger(occurredAtMs) && occurredAtMs >= 0 && occurredAtMs <= SIGNAL_TIME_MAX_MS)) {
     return `\`source.occurredAtMs\` must be whole epoch milliseconds from 0 to ${SIGNAL_TIME_MAX_MS}.`;
   }
+  if (subject !== void 0 && !fits(subject.kind, DETECTOR_ID)) {
+    return "`subject.kind` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
+  }
+  if (subject?.key !== void 0 && !(subject.key.length <= MAX_POINTER && POINTER.test(subject.key))) {
+    return `\`subject.key\` must be ${POINTER_RULE}.`;
+  }
+  if (after !== void 0 && !isWhole(after.observationId, 1)) {
+    return "`after.observationId` must be a positive whole number: the id of a stored signal.";
+  }
+  if (reuse !== void 0) {
+    if (!isWhole(reuse.maxAgeMs, 1)) {
+      return `\`reuse.maxAgeMs\` must be whole milliseconds from 1 to ${SIGNAL_TIME_MAX_MS}.`;
+    }
+    if (subject?.key === void 0) {
+      return "`reuse` needs `subject.key`: a stored answer is reused only for the same subject.";
+    }
+  }
   const names = Object.keys(questions);
   if (names.length === 0 || names.length > MAX_QUESTIONS) {
     return `\`questions\` must ask 1 to ${MAX_QUESTIONS} questions.`;
@@ -132,5 +268,8 @@ export {
   MAX_CHOICE_LABELS,
   SIGNAL_TIME_MAX_MS,
   createFallbackOnlySignals,
-  invalidObservation
+  createSignalEngine,
+  invalidObservation,
+  signalAnswersPass,
+  signalDigest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.5",
+  "version": "0.13.1",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -17,6 +17,10 @@
       "types": "./dist/kay-app.d.ts",
       "default": "./dist/kay-app.js"
     },
+    "./fs": {
+      "types": "./dist/fs.d.ts",
+      "default": "./dist/fs.js"
+    },
     "./kay-agent/testing": {
       "types": "./dist/kay-agent-testing.d.ts",
       "default": "./dist/kay-agent-testing.js"

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

@@ -1,11 +1,11 @@
 ---
 name: directory-plugin-authoring
-description: "Author, scaffold, debug, or iterate on a Kay directory plugin (one the user writes in ~/.kay/plugins/<name>). Use when creating a new local plugin, when a plugin does not appear in Kay after installation, when enabling it fails with 'pluginActivation names a plugin that is not installed', when Settings → Plugins shows 'failed to load' with no toggle, when @kay/plugin-sdk imports fail to resolve, when a plugin declares a ui.tsx that nothing typechecks, or when changes to a plugin do not take effect. For installing plugins from a git repository source, use the manage-plugins skill instead; for first-party bundled plugins under plugins/ in the kay repo, use the bundled-plugin guidance there."
+description: "Author, scaffold, debug, or iterate on a Bonsai directory plugin (one the user writes in ~/.kay/plugins/<name>). Use when creating a new local plugin, when a plugin does not appear in Bonsai after installation, when enabling it fails with 'pluginActivation names a plugin that is not installed', when Settings → Plugins shows 'failed to load' with no toggle, when @kay/plugin-sdk imports fail to resolve, when a plugin declares a ui.tsx that nothing typechecks, or when changes to a plugin do not take effect. For installing plugins from a git repository source, use the manage-plugins skill instead; for first-party bundled plugins under plugins/ in the kay repo, use the bundled-plugin guidance there."
 ---
 
 # Directory plugin authoring
 
-A directory plugin is a plugin the user authors in `~/.kay/plugins/<name>/`, outside the Kay
+A directory plugin is a plugin the user authors in `~/.kay/plugins/<name>/`, outside the Bonsai
 repo. The full authoring guide is [`docs/directory-plugins.md`](../../docs/directory-plugins.md)
 and the SDK reference is `packages/plugin-sdk/README.md`; this skill is the routing layer that
 keeps an agent on the paved path and out of the known pits.
@@ -13,7 +13,7 @@ keeps an agent on the paved path and out of the known pits.
 ## Confirm the checkout is current before you scaffold
 
 `pnpm create-plugin` writes absolute type paths (`tsconfig.json`, `package.json`) pointing at
-whichever Kay checkout invoked it, with no staleness warning. A checkout far behind `origin/main`
+whichever Bonsai checkout invoked it, with no staleness warning. A checkout far behind `origin/main`
 — one was 752 commits behind — typechecks the new plugin against stale `@kay/plugin-sdk` types,
 and it looks clean: every wrong shape it produced (a `content` object instead of
 `run`/`openBeside` on `PaneActionDescriptor`, `SearchField`'s `onChange` instead of
@@ -40,7 +40,7 @@ pnpm --filter @kay/plugin-sdk build   # once per checkout, if not built
 pnpm create-plugin --id com.example.widgets
 ```
 
-Run from the root of a Kay checkout. It writes a working plugin (manifest, entrypoint, tsconfig,
+Run from the root of a Bonsai checkout. It writes a working plugin (manifest, entrypoint, tsconfig,
 README) that already typechecks and loads; `--tier starter` adds a URI module, a bundled skill,
 and a standalone `node --test` test to copy from. Add `--ui` (either tier) when the plugin needs a
 page: it writes `ui.tsx`, declares the `kay.ui` entrypoint, and generates the UI typecheck config
@@ -61,7 +61,7 @@ cannot happen.
 pnpm plugin:check ~/.kay/plugins/widgets
 ```
 
-Run from the root of a Kay checkout, against the plugin directory. It runs the daemon's OWN
+Run from the root of a Bonsai 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.
@@ -87,10 +87,10 @@ disclosure audit, or an id another installed plugin already claims.
   exports exist).
 - The daemon's chord loader bundles each declared TypeScript entrypoint and its relative imports.
   It keeps `@kay/plugin-sdk` imports external and resolves them to the running app's own built SDK.
-  Multi-file plugins are supported, and no plugin-local build is needed for Kay to load them.
+  Multi-file plugins are supported, and no plugin-local build is needed for Bonsai to load them.
 - Corollary: **bare `node` outside the daemon cannot resolve `@kay/plugin-sdk`** from the plugin
   directory unless the plugin has its own SDK dependency. That failure says nothing about whether
-  the plugin will load in Kay. The `starter` tier's test setup creates the symlink needed for its
+  the plugin will load in Bonsai. The `starter` tier's test setup creates the symlink needed for its
   standalone test; a published SDK dependency is the other standalone option.
 - Typecheck with `npm run typecheck` inside the plugin directory; the scaffold's generated
   tsconfig maps the SDK's types via `paths`.
@@ -160,18 +160,18 @@ list` names the exact local root — because writing into the wrong one produces
    never appears and no diagnostic anywhere.
 
 2. **Enable it once.** Directory plugins are disabled on arrival (fail-closed: writing files in
-   your own plugin folder is how Kay DISCOVERS it, not consent to run it). Flip the toggle in
-   Settings → Plugins → your plugin's detail pane, or ask Kay to write the `installs` row's
+   your own plugin folder is how Bonsai DISCOVERS it, not consent to run it). Flip the toggle in
+   Settings → Plugins → your plugin's detail pane, or ask Bonsai to write the `installs` row's
    `enabled` field. Enabling reconciles live, and contributions reach the agent's **next**
    session, not the current one.
 3. **Edit, then commit.** `git add -A && git commit` makes the new code available.
-   Kay loads an isolated snapshot of HEAD and activates it live; no push or restart
+   Bonsai loads an isolated snapshot of HEAD and activates it live; no push or restart
    is needed. Uncommitted edits, staged additions, deleted working files and runtime
    writes do not execute, including at cold boot. The detail pane's **Running
    commit** identifies the serving snapshot. Try new tools in a fresh session;
    an existing session may still hold its previous generation.
 
-   Kay notices a commit within about 10 seconds even with no file events, and acquiring it may
+   Bonsai 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
@@ -208,7 +208,7 @@ 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. **Run `pnpm plugin:check <dir>`** from a Kay checkout. It validates `kay-plugin.json` against
+1. **Run `pnpm plugin:check <dir>`** from a Bonsai 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.
@@ -230,12 +230,13 @@ the detail pane's **Running commit** row for the revision.
 One thing no commit proves: whether the UI entrypoint bundles in a **packaged** build. esbuild's
 native binary resolution can fail silently inside `app.asar` (`ui_entrypoint_bundle_failed`), and
 the only trace is `ui-app.directory-load-failed` in the day's `kay-<date>.jsonl` log —
-`plugin://<id>` still reads enabled with no failure noted, and the pane simply has no overflow
-menu. Current builds carry the fix (#8014). A dev app runs unpackaged and never exercises that
-path, so report the packaged case as unverified instead of assuming it either way.
+`plugin://<id>` still reads enabled with no failure noted, and the pane's overflow menu simply
+lacks the plugin's row. Current builds carry the fix (#8014). A dev app runs unpackaged and
+never exercises that path, so report the packaged case as unverified instead of assuming it
+either way.
 
 Dev-instance warning: a worktree dev app (`pnpm dev:kay`) is a **separate daemon** from the
-user's installed Kay, with its own config store, consent records, and plugin roster. A plugin
+user's installed Bonsai, with its own config store, consent records, and plugin roster. A plugin
 visible in one is invisible to the other, and a `config://settings/pluginActivation` write from
 a session in one daemon validates against that daemon's roster only. #7732 was two daemons'
 outputs conflated into one impossible-looking bug; always ask "which daemon am I looking at?"
@@ -283,4 +284,4 @@ file.
 - [`docs/directory-plugins.md`](../../docs/directory-plugins.md) — the authoring guide:
   manifest shape, the enable gate and what it does not gate, trust tiers, diagnostics.
 - `packages/plugin-sdk/README.md` — the SDK surface.
-- `packages/plugin-sdk/PUBLISHED.md` — installing the published SDK outside a Kay checkout.
+- `packages/plugin-sdk/PUBLISHED.md` — installing the published SDK outside a Bonsai checkout.