@yaklabs-ai/plugin-sdk 0.8.4

package/dist/phase-shift.js

@@ -0,0 +1,180 @@
+// packages/plugin-protocol/dist/phase-shift.js
+import { z } from "zod";
+
+// packages/plugin-protocol/dist/transcript.js
+function branchEntryIds(entries) {
+  const last = entries[entries.length - 1];
+  if (last === void 0)
+    return EMPTY_BRANCH_IDS;
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  const onBranch = /* @__PURE__ */ new Set();
+  let cursor = last.type === "leaf" ? last.targetId ?? null : last.id;
+  while (cursor !== null && !onBranch.has(cursor)) {
+    onBranch.add(cursor);
+    cursor = byId.get(cursor)?.parentId ?? null;
+  }
+  return onBranch;
+}
+var EMPTY_BRANCH_IDS = /* @__PURE__ */ new Set();
+
+// packages/plugin-protocol/dist/phase-shift.js
+var PHASE_SHIFT_EXTENSION_ID = "kay.phase-shift";
+var PHASE_SHIFT_ENTRY_NAME = "observation";
+var PHASE_SHIFT_CUSTOM_TYPE = `ext:${PHASE_SHIFT_EXTENSION_ID}:${PHASE_SHIFT_ENTRY_NAME}`;
+var PHASE_SHIFT_TIMELINE_CUSTOM_TYPE = `ext:${PHASE_SHIFT_EXTENSION_ID}:timeline`;
+var PHASE_SHIFT_DETECTOR_VERSION = "activity-memory-v1";
+var entryId = z.string().min(1).max(256);
+var purpose = z.string().trim().min(1).max(320);
+var sourceTime = z.iso.datetime();
+var phaseShiftMemorySchema = z.object({
+  startEntryId: entryId,
+  purpose,
+  anchors: z.array(z.object({ entryId, excerpt: z.string().max(250) })).min(1).max(3)
+});
+var phaseShiftCostSchema = z.object({
+  amountUsd: z.number().nonnegative(),
+  amountBasis: z.enum(["measured", "list-estimate", "unknown"]),
+  inputTokens: z.number().int().nonnegative(),
+  outputTokens: z.number().int().nonnegative(),
+  /**
+   * The highest provider-attempt ordinal this check accounted for; recovery
+   * after a failure makes it more than one. An attempt that threw before
+   * reporting usage is invisible to accounting, so this is a lower bound on
+   * what the provider was actually asked to do.
+   */
+  attempts: z.number().int().positive()
+});
+var observationFields = {
+  detectorVersion: z.literal(PHASE_SHIFT_DETECTOR_VERSION),
+  modelReference: z.string().min(1).max(256),
+  observedAt: z.iso.datetime(),
+  throughEntryId: entryId,
+  windowEntryIds: z.array(entryId).min(1).max(40),
+  memory: phaseShiftMemorySchema
+};
+var changeFields = {
+  startEntryId: entryId,
+  relation: z.enum(["outcome", "phase"]),
+  reason: z.string().trim().min(1).max(2e3),
+  purposeAfter: purpose
+};
+var phaseShiftObservationV1Schema = z.object({
+  version: z.literal(1),
+  ...observationFields,
+  changes: z.array(z.object(changeFields)).max(39)
+});
+var phaseShiftObservationV2Schema = z.object({
+  version: z.literal(2),
+  ...observationFields,
+  /** Timestamp of the `windowEntryIds[0]` entry: where this check's coverage starts. */
+  windowStartAt: sourceTime,
+  /** Timestamp of the `throughEntryId` entry: where this check's coverage ends. */
+  throughAt: sourceTime,
+  /** What this check cost to run; absent on a record written before it was accounted. */
+  cost: phaseShiftCostSchema.optional(),
+  changes: z.array(z.object({
+    ...changeFields,
+    /** Timestamp of the `startEntryId` entry: when the new work began. */
+    startedAt: sourceTime
+  })).max(39)
+});
+var phaseShiftObservationSchema = z.discriminatedUnion("version", [
+  phaseShiftObservationV1Schema,
+  phaseShiftObservationV2Schema
+]);
+function acceptedPhaseShiftObservationEntries(branch, options) {
+  const positions = new Map(branch.flatMap((entry, index) => entry.type === "message" || entry.type === "custom_message" ? [[entry.id, index]] : []));
+  const accepted = [];
+  let through = -1;
+  let start = -1;
+  for (let index = 0; index < branch.length; index += 1) {
+    const entry = branch[index];
+    if (entry.type !== "custom" || entry.customType !== PHASE_SHIFT_CUSTOM_TYPE)
+      continue;
+    const parsed = phaseShiftObservationSchema.safeParse(entry.data);
+    if (!parsed.success) {
+      options?.onRefusedRecord?.({
+        entryId: entry.id,
+        issues: issueMarkers(parsed.error)
+      });
+      continue;
+    }
+    const observation = parsed.data;
+    const cutoff = positions.get(observation.throughEntryId) ?? -1;
+    const memoryStart = positions.get(observation.memory.startEntryId) ?? -1;
+    const window = observation.windowEntryIds.map((id) => positions.get(id) ?? -1);
+    const onsets = observation.changes.map((change) => positions.get(change.startEntryId) ?? -1);
+    if (cutoff <= through || cutoff >= index || memoryStart < 0 || memoryStart < start || memoryStart > cutoff || window.at(-1) !== cutoff || window.some((position, i) => position < 0 || i > 0 && position <= window[i - 1]) || onsets.some((position, i) => !window.includes(position) || position <= window[0] || position <= start || i > 0 && position <= onsets[i - 1]) || observation.memory.anchors.some((anchor) => {
+      const position = positions.get(anchor.entryId) ?? -1;
+      return position < memoryStart || position > cutoff;
+    }))
+      continue;
+    const lastChange = observation.changes.at(-1);
+    if (lastChange !== void 0) {
+      if (observation.memory.startEntryId !== lastChange.startEntryId || observation.memory.purpose !== lastChange.purposeAfter)
+        continue;
+    } else {
+      const previous = accepted.at(-1)?.observation;
+      if (previous !== void 0 && JSON.stringify(observation.memory) !== JSON.stringify(previous.memory)) {
+        continue;
+      }
+    }
+    accepted.push({ entryId: entry.id, observation });
+    through = cutoff;
+    start = memoryStart;
+  }
+  return accepted;
+}
+function acceptedPhaseShiftObservations(branch, options) {
+  return acceptedPhaseShiftObservationEntries(branch, options).map((entry) => entry.observation);
+}
+function issueMarkers(error) {
+  return error.issues.slice(0, 3).map((issue) => {
+    const record = issue;
+    const code = typeof record.code === "string" ? record.code : "issue";
+    const path = Array.isArray(record.path) ? record.path.join(".") : "";
+    return `${code}@${path}`;
+  }).join(";").slice(0, 120);
+}
+function phaseShiftTimelineRecord(observation) {
+  return {
+    version: 1,
+    detectorVersion: observation.detectorVersion,
+    modelReference: observation.modelReference,
+    observedAt: observation.observedAt,
+    windowStartEntryId: observation.windowEntryIds[0],
+    windowStartAt: observation.windowStartAt,
+    throughEntryId: observation.throughEntryId,
+    throughAt: observation.throughAt,
+    purpose: observation.memory.purpose,
+    ...observation.cost === void 0 ? {} : { cost: observation.cost },
+    changes: observation.changes.map((change) => ({
+      startEntryId: change.startEntryId,
+      startedAt: change.startedAt,
+      relation: change.relation,
+      reason: change.reason,
+      purposeAfter: change.purposeAfter
+    }))
+  };
+}
+function phaseShiftTimelineFromEntries(entries) {
+  const onBranch = branchEntryIds(entries);
+  const branch = entries.filter((entry) => onBranch.has(entry.id));
+  const timestamps = new Map(branch.map((entry) => [entry.id, entry.timestamp]));
+  const at = (id) => timestamps.get(id) ?? "";
+  return acceptedPhaseShiftObservations(branch).map((observation) => observation.version === 2 ? phaseShiftTimelineRecord(observation) : phaseShiftTimelineRecord({
+    ...observation,
+    version: 2,
+    windowStartAt: at(observation.windowEntryIds[0]),
+    throughAt: at(observation.throughEntryId),
+    changes: observation.changes.map((change) => ({
+      ...change,
+      startedAt: at(change.startEntryId)
+    }))
+  }));
+}
+export {
+  PHASE_SHIFT_CUSTOM_TYPE,
+  PHASE_SHIFT_TIMELINE_CUSTOM_TYPE,
+  phaseShiftTimelineFromEntries
+};

package/dist/transcript.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The ids on a session's active branch: the leaf chain walked parent-ward from
+ * the tip, which a trailing `leaf` marker moves. Empty for an empty log.
+ *
+ * One walk shared by every reader of "is this entry still live", so a rewind
+ * means the same thing to every projection that calls it. Self-guarding
+ * against a cyclic or otherwise malformed parent chain: the loop stops the
+ * moment it revisits an id, so a cycle yields the cycle's own ids rather than
+ * looping forever.
+ */
+export declare function branchEntryIds(entries: readonly TranscriptTreeEntry[]): ReadonlySet<string>;
+
+/**
+ * Every `type: "custom"` entry of one `customType`, oldest→newest, with every
+ * field ({@link TranscriptSourceEntry}'s id/timestamp/tree links plus the
+ * entry's own `data`) preserved unchanged — `data` is returned exactly as it
+ * arrived, opaque and unvalidated, never coerced toward a schema this module
+ * cannot know.
+ *
+ * `options.branch` is required, deliberately: `"active"` filters to
+ * {@link branchEntryIds}; `"all"` returns every matching entry in the flat
+ * log, rewind-abandoned or not. A silent default would let a caller reach
+ * for whichever one it did not mean to — pick `"all"` only when the caller
+ * itself needs to reason about abandoned entries (an audit, a recovery
+ * tool); an ordinary reader states `"active"` explicitly.
+ */
+export declare function customEntriesFromEntries<T extends TranscriptSourceEntry = TranscriptSourceEntry>(entries: readonly T[], customType: string, options: {
+    readonly branch: "active" | "all";
+}): readonly T[];
+
+/** The fields the customType selector needs off a session entry. */
+export declare interface TranscriptEntry {
+    readonly id: string;
+    readonly type: string;
+    readonly customType?: string;
+    /** Opaque. Never parsed or validated here — a feature's own schema owns that. */
+    readonly data?: unknown;
+}
+
+/**
+ * A tree entry plus the ISO timestamp the timeline projections read alongside
+ * the walk result (`turnSegments`, `phaseShiftTimelineFromEntries`).
+ */
+export declare interface TranscriptSourceEntry extends TranscriptTreeEntry {
+    readonly timestamp: string;
+}
+
+/**
+ * A session entry as {@link branchEntryIds} reads it: the fields above plus the
+ * tree links the walk follows to find the active branch. No timestamp: the walk
+ * never reads one, and a live v2 entry carries epoch milliseconds where a raw
+ * v3 log carries an ISO string, so requiring either shape here would force one
+ * class of caller to convert entries it only wants walked.
+ */
+declare interface TranscriptTreeEntry extends TranscriptEntry {
+    readonly parentId?: string | null;
+    readonly targetId?: string | null;
+}
+
+export { }

package/dist/transcript.js

@@ -0,0 +1,23 @@
+// packages/plugin-protocol/dist/transcript.js
+function branchEntryIds(entries) {
+  const last = entries[entries.length - 1];
+  if (last === void 0)
+    return EMPTY_BRANCH_IDS;
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  const onBranch = /* @__PURE__ */ new Set();
+  let cursor = last.type === "leaf" ? last.targetId ?? null : last.id;
+  while (cursor !== null && !onBranch.has(cursor)) {
+    onBranch.add(cursor);
+    cursor = byId.get(cursor)?.parentId ?? null;
+  }
+  return onBranch;
+}
+var EMPTY_BRANCH_IDS = /* @__PURE__ */ new Set();
+function customEntriesFromEntries(entries, customType, options) {
+  const onBranch = options.branch === "all" ? null : branchEntryIds(entries);
+  return entries.filter((entry) => entry.type === "custom" && entry.customType === customType && (onBranch === null || onBranch.has(entry.id)));
+}
+export {
+  branchEntryIds,
+  customEntriesFromEntries
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@yaklabs-ai/plugin-sdk",
+  "version": "0.8.4",
+  "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
+  "author": "YakLabs",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./kay-agent": {
+      "types": "./dist/kay-agent.d.ts",
+      "default": "./dist/kay-agent.js"
+    },
+    "./kay-app": {
+      "types": "./dist/kay-app.d.ts",
+      "default": "./dist/kay-app.js"
+    },
+    "./kay-agent/testing": {
+      "types": "./dist/kay-agent-testing.d.ts",
+      "default": "./dist/kay-agent-testing.js"
+    },
+    "./disclosure": {
+      "types": "./dist/disclosure.d.ts",
+      "default": "./dist/disclosure.js"
+    },
+    "./phase-shift": {
+      "types": "./dist/phase-shift.d.ts",
+      "default": "./dist/phase-shift.js"
+    },
+    "./transcript": {
+      "types": "./dist/transcript.d.ts",
+      "default": "./dist/transcript.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md",
+    "THIRD-PARTY-INVENTORY.json",
+    "skills"
+  ],
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@typesafe-ai/sdk": "0.6.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yaklabs-ai/kay.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,252 @@
+---
+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."
+---
+
+# Directory plugin authoring
+
+A directory plugin is a plugin the user authors in `~/.kay/plugins/<name>/`, outside the Kay
+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.
+
+## 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`
+— 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
+`onValueChange`, wrong `PageState` props) typechecked fine against the old types it was
+scaffolded from.
+
+So preflight the checkout, before scaffolding rather than after a typecheck already looked green:
+
+```
+git -C <kay-checkout> fetch origin && git -C <kay-checkout> rev-list --count HEAD..origin/main
+```
+
+A nonzero count means update that checkout first, or scaffold from a fresh `origin/main` worktree
+and rebuild `@kay/plugin-sdk` there. A green typecheck against stale types is evidence of nothing.
+The scaffold does the second half of this for you: it prints a warning when the checkout trails
+its last-fetched `origin/main`, and stamps the checkout's commit into the generated
+`tsconfig.json` header. It never fetches, so the `fetch` above is still yours to run; a checkout
+that has not fetched in a week reads as current to the scaffold.
+
+## Scaffold, never hand-roll
+
+```
+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,
+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
+described below. `--ui` also needs `pnpm --filter @kay/ui build` once per checkout; the scaffold
+stops and says so when that build is missing.
+
+Never hand-build a plugin as a tsc-compiled package and copy the output into `~/.kay/plugins/`.
+That path produces a plugin whose built `dist/` imports `@kay/plugin-sdk` through ordinary
+`node_modules` resolution, which cannot work from outside the monorepo — it shipped a
+failed-to-load plugin and a misfiled bug (#7732). The load fails with `ERR_MODULE_NOT_FOUND`,
+and symlinking `node_modules/@kay` into the copy does not rescue it either: pnpm's `.pnpm`
+layout does not expose workspace packages that way. The scaffold exists precisely so this
+cannot happen.
+
+## The SDK resolution contract
+
+- Plugin source imports `@kay/plugin-sdk/<subpath>` as a **bare specifier**
+  (`@kay/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure` — only declared
+  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.
+- 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
+  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`.
+- Chord compiles TypeScript syntax that native type stripping cannot execute, including `enum`,
+  `namespace` blocks, constructor parameter properties, and decorators. Typecheck before enabling
+  the plugin; a bundle error is reported as a target-load diagnostic.
+
+## A UI target: three files, its own typecheck, generated
+
+A plugin with a UI has three targets. Each declared daemon target is a bundle root, so its
+entrypoint may import other files in the plugin; `kay.agent` runs in the daemon per session and
+`kay.app` runs in the daemon once. `kay.ui` runs in the renderer through its own UI bundle, which is a single
+self-contained module: unlike the daemon targets, `ui.tsx` cannot import sibling files. A
+plugin UI contributes through `api.slots` (`registerPage`, `registerSidebarItem`,
+`registerPaneAction`, and the rest of `buildSlots` in
+`apps/kay/src/renderer/src/extension-loader/build-extension-api.ts`). A page gets its own
+activity-rail button when a `registerSidebarItem({ pageId, placement: "activityRail" })` from the
+same plugin points at it.
+
+**Icons: declare one plugin icon, override only where you mean it.** Set the manifest `icon` (a
+package-relative SVG) and every surface the plugin contributes inherits it: reference pills, its
+rail button, and its pages' tabs, pane headers and palette entries (shown as your full-colour mark
+on a small white tile). Set `icon` on a `registerSidebarItem` or `registerPage` descriptor only to
+show a monochrome glyph there instead (a glyph name such as `"git-branch"`, or `{ svg }`); a page
+and its rail item borrow each other's glyph, so one declaration covers the destination. Full
+precedence: `packages/kay-frontend-sdk/ARCHITECTURE.md`, "Plugin icon".
+
+`ui.tsx` has no `node_modules` of its own. The renderer bundles it and rewrites its `react` and
+`@kay/*` imports to the host's `__KAY_UI_RUNTIME__` singletons, so the agent `tsconfig.json`
+cannot cover it, and a plugin whose UI nothing typechecks has shipped three wrong API shapes at
+once. `pnpm create-plugin --ui` generates `tsconfig.ui.json` for exactly this: its `paths` are
+derived from the bundler's own shim set (`uiRuntimeShimModules` in `@kay/ui-app-bundler`), each
+specifier mapped to the type entry the renderer binds it to, and `npm run typecheck` runs both
+configs. Do not hand-write the map; when the bundler's set changes, the scaffold's test fails and
+the generated config follows.
+
+Two facts about that config worth knowing when you read errors from it:
+
+- The bare `@kay/frontend-sdk` is typed against the SDK's `ui-runtime` facade, because that is
+  what the renderer binds it to. The facade carries the SDK's whole type surface, so
+  `KayUiExtensionApi` and every descriptor type import fine; a **value** only the package's main
+  entry exports fails to compile there (TS1362, "exported using export type"), which is the
+  compiler telling you the running extension would receive `undefined`.
+- It typechecks `ui.tsx` alone, as a browser module: `Bundler` resolution, automatic JSX, DOM
+  libs, no Node globals. The agent config keeps `**/*.ts`, so the two programs never overlap.
+
+For a plugin scaffolded before `--ui` existed, scaffold a throwaway `--ui` plugin from the same
+checkout and copy its `tsconfig.ui.json` and the second `typecheck` command into yours; `--force`
+rewrites every generated file, including `entrypoint.ts`, so do not point it at a plugin you have
+edited.
+
+## The iteration loop
+
+1. **Write the directory under the local plugin root, and back it with git.** A local plugin
+   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 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
+   `~/.kay/plugins`. Ask the daemon you are actually talking to rather than assuming — `sources
+list` names the exact local root — because writing into the wrong one produces a plugin that
+   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
+   `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
+   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.
+
+   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
+   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
+   `contributes` that carries a capability — a `contextContributors` entry needs
+   `dynamic-context.register` for that id, a data source needs `app-data.register`, a foreign
+   config section needs `config.declare-section` — must ALSO be granted before the plugin can
+   use it. Until then `activate()` throws at the first call, the plugin reads
+   `activation-failed`, its row carries a `grant` need naming the exact claim, and the page
+   shows the refusal text. The answer is the grant verb with that same claim shape (target,
+   slug, envelope), after which the activation is retried for you:
+
+   ```json
+   {
+     "target": "kay.app",
+     "slug": "dynamic-context.register",
+     "envelope": { "contributor": "<your-contributor-id>" }
+   }
+   ```
+
+   Granting is the human-approval gate, so an agent writing the row's `grants` raises a diff for
+   the user to accept; enabling and disabling do not.
+
+5. **Iterate in a fresh session.** A typecheck or direct tool call cannot show whether an agent
+   can discover and use the surface; try the user-goal case in a real new session.
+
+## Before you commit, verify what the commit will activate
+
+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.
+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.
+3. **Typecheck every target**: `npm run typecheck` runs the agent config and, for a `--ui`
+   scaffold, `tsconfig.ui.json` after it. A plugin with a `ui.tsx` and only one config has an
+   unchecked target.
+4. **Round-trip the targets against each other.** They share no imports, so a typecheck proves
+   the shapes compile, not that `kay.app` and `kay.agent` agree on the data they share: write
+   through the UI's daemon endpoint, read it back through the agent's `scheme://` module, then
+   the reverse.
+
+Then commit — that is what activates it — and confirm the serving snapshot is the commit you
+just made: `read plugin://<id>` for the expected tools and skills with no load diagnostic, and
+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.
+
+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
+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?"
+
+## When it does not load
+
+Read the Plugins page before the logs; every rejection stage produces a named diagnostic shown
+on the plugin's row (or on the plugin source's row, when the whole source found nothing).
+
+- **"failed to load" with no toggle** is the synthesized row for an install that failed before
+  producing a working plugin — it is untogglable by design. Fix the load failure; the toggle
+  belongs to the healthy row.
+- **"names a plugin that is not installed"** means exactly that in this daemon: the plugin is
+  not in the composed roster. Check a scan actually saw it (`plugin-directory-scan.finished`
+  logs on every walk, not only at boot — an unconsented root skips the scan entirely), check
+  the root you wrote into is the one `sources list` names for THIS daemon, then check you are
+  talking to the daemon you think you are.
+- **A plugin that reads `activation-failed` has usually been refused a capability**, not broken
+  its code: read the reason on its row (the failed target carries the refusal text) and grant
+  the claim it names.
+- **A symlinked plugin directory may be skipped by the scan without a diagnostic.** If the scan
+  accepts N-1 of your N directories with zero diagnostics, look for a symlink.
+- **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.
+
+## Declaring a scheduled workflow
+
+A directory plugin does not request workflows in its manifest. During `kay.app` activation, call
+`app.workflows.define(localId, { name, trigger, run })` to put a durable, daemon-scheduled row on
+the Automations page. The host raises the `workflows.define` claim for every `kay.app` plugin; a
+bundled install holds every grant, while a directory plugin needs the user to add that grant to its
+`installs` row. Source class no longer decides workflow authority, and the capability is ABSENT
+rather than refused when ungranted, so guard on `app.workflows === undefined`.
+
+The product-agent procedure is the builtin skill `create-workflow`
+(`packages/agent-runtime/src/kay/builtin-skills/`), and the API reference is the "Durable Workflows
+In A Plugin" section of `apps/kay/agent-docs/extensions-api.md`. Keep those two in step with this
+file.
+
+## Reference map
+
+- [`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.