@yaklabs-ai/plugin-sdk 0.13.2 → 0.13.3

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

@@ -1,6 +1,6 @@
 ---
 name: directory-plugin-authoring
-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."
+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 @bonsai/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
@@ -14,7 +14,7 @@ keeps an agent on the paved path and out of the known pits.
 
 `pnpm create-plugin` writes absolute type paths (`tsconfig.json`, `package.json`) pointing at
 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,
+— one was 752 commits behind — typechecks the new plugin against stale `@bonsai/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
@@ -27,7 +27,7 @@ git -C <kay-checkout> fetch origin && git -C <kay-checkout> rev-list --count HEA
 ```
 
 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.
+and rebuild `@bonsai/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
@@ -36,7 +36,7 @@ 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 --filter @bonsai/plugin-sdk build   # once per checkout, if not built
 pnpm create-plugin --id com.example.widgets
 ```
 
@@ -44,14 +44,14 @@ Run from the root of a Bonsai checkout. It writes a working plugin (manifest, en
 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
+described below. `--ui` also needs `pnpm --filter @bonsai/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
+That path produces a plugin whose built `dist/` imports `@bonsai/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`
+and symlinking `node_modules/@bonsai` 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.
 
@@ -62,7 +62,7 @@ pnpm plugin:check ~/.kay/plugins/widgets
 ```
 
 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),
+manifest schema and contract resolver (imported from `@bonsai/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.
 
@@ -82,13 +82,13 @@ 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**
-  (`@kay/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure` — only declared
+- Plugin source imports `@bonsai/plugin-sdk/<subpath>` as a **bare specifier**
+  (`@bonsai/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.
+  It keeps `@bonsai/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 Bonsai to load them.
-- Corollary: **bare `node` outside the daemon cannot resolve `@kay/plugin-sdk`** from the plugin
+- Corollary: **bare `node` outside the daemon cannot resolve `@bonsai/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 Bonsai. The `starter` tier's test setup creates the symlink needed for its
   standalone test; a published SDK dependency is the other standalone option.
@@ -106,7 +106,7 @@ entrypoint may import other files in the plugin; `kay.agent` runs in the daemon
 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
+`packages/kay-renderer/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.
 
@@ -119,17 +119,17 @@ and its rail item borrow each other's glyph, so one declaration covers the desti
 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`
+`@bonsai/*` 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
+derived from the bundler's own shim set (`uiRuntimeShimModules` in `@bonsai/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
+- The bare `@bonsai/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
@@ -210,9 +210,9 @@ a failure class the load would otherwise be the first thing to surface:
 
 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
+   `@bonsai/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`.
+2. **Run the disclosure audit yourself**: `auditPluginDisclosure` from `@bonsai/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`