@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/onboarding/starter-packs.ts

@@ -0,0 +1,182 @@
+/**
+ * Starter packs: the pages and the plugin a new knowledge base can be filled
+ * with in one click, chosen by what the team does.
+ *
+ * A pack is a folder under the packs root (`starter-packs/` in this package,
+ * or a distribution's `STARTER_PACKS_DIR`):
+ *
+ *   <id>/pack.yaml          id, name, description, order, firstPagePrompt, suggestedPages
+ *   <id>/KnowledgeBase/…    pages, under the DEFAULT layout's folder names
+ *   <id>/Plugins/<name>/…   a team plugin in the normal plugin layout
+ *   <id>/Skills/…           shared skills, if a pack carries any
+ *
+ * The three folders are written under the deployment's OWN names for them
+ * (`KnowledgeBase/` lands in whatever `knowledgeBaseDir` is), so a pack is
+ * authored once and fits every layout. Anything else in a pack folder (a
+ * README, notes for whoever maintains it) is the pack's, not the knowledge
+ * base's, and is never copied.
+ *
+ * A pack that does not read as one — no `pack.yaml`, a field missing or of
+ * the wrong kind, an id that is not its folder's name — is passed over with
+ * a warning: one broken folder must not take the choice away from everyone.
+ *
+ * The disk is read through the one walk and the one probe
+ * (`shared/fs.contract.ts`), handed in by the caller; only a file's bytes are
+ * read here, which neither contract covers.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { renderKbLayoutPlaceholders, type KbLayout } from '@bevel-software/platform-shared';
+import type { IFsProbe, ITreeWalker, WalkedEntry } from '../../shared/fs.contract.js';
+import { logger } from '../../shared/logging.js';
+import { utf8Text } from '../../shared/utf8-text.js';
+
+const log = logger('starter-packs');
+
+/** The file that makes a folder a pack. */
+export const PACK_MANIFEST = 'pack.yaml';
+
+/** The answer that chooses no pack: "Skip, I'll start from scratch". Never a pack's id. */
+export const NO_STARTER_PACK = 'none';
+
+/** A pack id: the folder's name, kebab-case, so it is safe in a URL, a setting and a path. */
+const PACK_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The pack's own folders, by their default-layout names, and the layout key each one is written under. */
+export const PACK_ROOTS: ReadonlyArray<readonly [string, keyof Pick<KbLayout, 'knowledgeBaseDir' | 'pluginsDir' | 'skillsDir'>]> = [
+  ['KnowledgeBase', 'knowledgeBaseDir'],
+  ['Plugins', 'pluginsDir'],
+  ['Skills', 'skillsDir'],
+];
+
+/** What a chip shows, and the order the chips come in. */
+export interface StarterPackSummary {
+  id: string;
+  name: string;
+  description: string;
+  order: number;
+}
+
+export interface StarterPack extends StarterPackSummary {
+  /** Replaces the generic "write your first page" request for a team that chose this pack. */
+  firstPagePrompt: string;
+  /** The pages the agent's first-run note offers to draft. */
+  suggestedPages: string[];
+  /** The pack's folder, absolute. */
+  dir: string;
+}
+
+/** One file a pack would add, at the path it would have in the knowledge base. */
+export interface StarterPackFile {
+  /** Repository-relative, under the deployment's layout: `KnowledgeBase/About us.md`, `Plugins/x/skills/y/SKILL.md`. */
+  repoPath: string;
+  /** Which of the pack's folders it came from, by its default name. */
+  root: (typeof PACK_ROOTS)[number][0];
+  /** The bytes to write: text with the layout placeholders filled, or the file as it is. */
+  content: string | Buffer;
+}
+
+/**
+ * Every valid pack under `root`, chip order first (then name). A root that
+ * is not there offers no packs; it is not an error, since a distribution may
+ * ship none.
+ */
+export async function loadStarterPacks(disk: IFsProbe, root: string): Promise<StarterPack[]> {
+  let entries: WalkedEntry[] | null;
+  try {
+    entries = await disk.listDir(root);
+  } catch (err) {
+    log.warn(`could not read the starter packs folder "${root}" — no packs offered:`, { err });
+    return [];
+  }
+  if (entries === null) return [];
+  const packs: StarterPack[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const pack = await readStarterPack(disk, path.join(root, entry.name));
+    if (pack) packs.push(pack);
+  }
+  return packs.sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
+}
+
+/** The pack in `dir`, or null (with a warning saying why) when it does not read as one. */
+export async function readStarterPack(disk: IFsProbe, dir: string): Promise<StarterPack | null> {
+  const folder = path.basename(dir);
+  let raw: string;
+  try {
+    raw = await disk.readTextFile(path.join(dir, PACK_MANIFEST));
+  } catch {
+    log.warn(`starter pack "${folder}" has no readable ${PACK_MANIFEST} — skipped.`);
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (err) {
+    log.warn(`starter pack "${folder}": ${PACK_MANIFEST} is not valid YAML — skipped.`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+  const problem = packProblem(parsed, folder);
+  if (problem) {
+    log.warn(`starter pack "${folder}": ${problem} — skipped.`);
+    return null;
+  }
+  const m = parsed as Record<string, unknown>;
+  return {
+    id: m.id as string,
+    name: (m.name as string).trim(),
+    description: (m.description as string).trim(),
+    order: m.order as number,
+    firstPagePrompt: (m.firstPagePrompt as string).trim(),
+    suggestedPages: (m.suggestedPages as string[]).map((p) => p.trim()),
+    dir,
+  };
+}
+
+/** Why a parsed `pack.yaml` is not a pack, or null when it is one. */
+export function packProblem(manifest: unknown, folder: string): string | null {
+  if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {
+    return `${PACK_MANIFEST} is not a mapping`;
+  }
+  const m = manifest as Record<string, unknown>;
+  if (typeof m.id !== 'string' || !PACK_ID_RE.test(m.id)) return '`id` must be lowercase letters, digits and hyphens';
+  if (m.id !== folder) return `\`id\` ("${m.id}") must be the folder's name`;
+  if (m.id === NO_STARTER_PACK) return `"${NO_STARTER_PACK}" is reserved for skipping`;
+  for (const key of ['name', 'description', 'firstPagePrompt'] as const) {
+    if (typeof m[key] !== 'string' || !(m[key] as string).trim()) return `\`${key}\` must be a non-empty string`;
+  }
+  if (typeof m.order !== 'number' || !Number.isFinite(m.order)) return '`order` must be a number';
+  if (!Array.isArray(m.suggestedPages) || m.suggestedPages.some((p) => typeof p !== 'string' || !p.trim())) {
+    return '`suggestedPages` must be a list of page names';
+  }
+  return null;
+}
+
+/**
+ * Every file the pack would add, at its path under `layout`, in walk order.
+ * The knowledge-base walk lists them: dot-entries are left behind (an
+ * editor's or an OS's droppings, never content), and so is anything that is
+ * not a regular file — a pack is files. A pack folder that is not there, or
+ * is a file where a folder was expected, holds nothing; a folder in one that
+ * cannot be listed is the error, since a pack with a hole is not the pack.
+ */
+export async function starterPackFiles(disk: ITreeWalker, pack: StarterPack, layout: Required<KbLayout>): Promise<StarterPackFile[]> {
+  const out: StarterPackFile[] = [];
+  for (const [root, layoutKey] of PACK_ROOTS) {
+    const base = path.join(pack.dir, root);
+    for (const rel of await disk.walkFiles(base, () => true, { strict: true })) {
+      const bytes = await fs.readFile(path.join(base, ...rel.split('/')));
+      const text = utf8Text(bytes);
+      out.push({
+        repoPath: `${layout[layoutKey]}/${rel}`,
+        root,
+        content: text === null ? bytes : renderKbLayoutPlaceholders(text, layout),
+      });
+    }
+  }
+  return out;
+}

package/src/modules/plugins/__tests__/plugins.tools.test.ts

@@ -6,7 +6,11 @@ import { InternalTokenService } from '../../tool-auth/internal-token.service.js'
 import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
 import { keyOrSessionAuth } from '../../tool-auth/key-or-session.middleware.js';
 import { createAuthMiddleware } from '../../auth/auth.middleware.js';
-import { registerPluginsTools, CREATE_PLUGIN, MY_PLUGIN } from '../plugins.tools.js';
+import { DEFAULT_KB_LAYOUT, validateKbLayout } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength } from '../../tool-registry/description-length.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { registerPluginsTools, CREATE_PLUGIN, myPluginDef, myPluginDescription } from '../plugins.tools.js';
 import { createPluginCreationRoutes } from '../plugins.routes.js';
 import { PluginProvisionError } from '../plugin-provision.service.js';
 
@@ -20,18 +24,165 @@ import { PluginProvisionError } from '../plugin-provision.service.js';
 
 const ALICE = { id: 'user-alice', email: 'alice@x.com', name: 'Alice' };
 
+/** `my_plugin` as the catalog lists it for `layout`, on the external surface. */
+async function listedMyPlugin(layout = DEFAULT_KB_LAYOUT): Promise<{ description: string }> {
+  const registry = new ToolRegistry();
+  registerPluginsTools(registry, testKbContext({ layout }));
+  const listed = (await registry.listExternal({ userEmail: ALICE.email })).find((t) => t.name === 'my_plugin');
+  expect(listed, 'my_plugin is not in the external catalog').toBeDefined();
+  return listed as { description: string };
+}
+
+/** The rule, in the words a client must be handed before any cut. */
+const RULE = [
+  'personal plugin',
+  'their own skills and tools',
+  'they go under the knowledge root',
+  'ask where under the knowledge root',
+  'restricted so only they can read it',
+  'never write it here, even if asked',
+];
+
 describe('the tool definitions', () => {
   it('describe the creation endpoints, and reach every surface', async () => {
     expect((CREATE_PLUGIN.tool_call_template as { url: string }).url).toBe('${API_URL}/api/plugins');
-    expect((MY_PLUGIN.tool_call_template as { url: string }).url).toBe('${API_URL}/api/plugins/personal');
+    expect((myPluginDef(DEFAULT_KB_LAYOUT).tool_call_template as { url: string }).url).toBe(
+      '${API_URL}/api/plugins/personal',
+    );
     const registry = new ToolRegistry();
-    registerPluginsTools(registry);
+    registerPluginsTools(registry, testKbContext());
     for (const tools of [await registry.listExternal({ userEmail: ALICE.email }), await registry.listInternal({ userEmail: ALICE.email })]) {
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(['my_plugin', 'create_plugin']));
     }
   });
 });
 
+/**
+ * What `my_plugin` TELLS an agent. A personal plugin holds its owner's skills
+ * and tools; nothing under the plugins root is in the knowledge graph and a
+ * personal plugin is readable only by its owner, so a note filed there is
+ * never found as knowledge again. The old description opened by calling the
+ * folder "their personal space in the knowledge base", which read as an
+ * invitation to file one. Pinned here because the text IS the change: nothing
+ * refuses such a write, before or after (see the last test in this block).
+ */
+describe('what my_plugin tells an agent about the personal plugin', () => {
+  it('states the rule, naming this deployment\'s knowledge root', async () => {
+    const { description } = await listedMyPlugin();
+    expect(description).toContain("The caller's personal plugin: their own skills and tools");
+    expect(description).toContain('Notes, knowledge and other documents do NOT go here; they go under the knowledge root.');
+    expect(description).toContain('The knowledge root here is `KnowledgeBase/`.');
+    // A private request gets a QUESTION and the restrictable folder, never the
+    // personal plugin — not even when the user asks for it outright.
+    expect(description).toContain('ask where under the knowledge root it should go');
+    expect(description).toContain('restricted so only they can read it');
+    expect(description).toContain('never write it here, even if asked');
+    // The name the app shows, and none of the three phrases that sent agents here.
+    for (const retired of ['personal space', 'private space', 'own space']) {
+      expect(description, retired).not.toContain(retired);
+    }
+  });
+
+  it('names a RENAMED knowledge root, and never the default one', async () => {
+    const renamed = { knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' };
+    const { description } = await listedMyPlugin(renamed);
+    expect(description).toContain('The knowledge root here is `Docs/`.');
+    expect(description).not.toContain('KnowledgeBase');
+  });
+
+  /**
+   * The save that completes first-run setup applies the names the admin just
+   * chose IN THAT REQUEST, with no restart, so a description built once at
+   * registration would go on naming a folder the deployment no longer has.
+   * Rewritten in place, which is why both surfaces see it: they hold the same
+   * object.
+   */
+  it('follows a layout applied after registration, on both surfaces', async () => {
+    const registry = new ToolRegistry();
+    const kb = testKbContext();
+    registerPluginsTools(registry, kb);
+    kb.applyLayout({ knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' });
+    for (const tools of [await registry.listExternal(), await registry.listInternal()]) {
+      const description = tools.find((t) => t.name === 'my_plugin')!.description!;
+      expect(description).toContain('The knowledge root here is `Docs/`.');
+      expect(description).not.toContain('KnowledgeBase');
+    }
+  });
+
+  /**
+   * claude.ai cuts a tool description near `CLIENT_SHORT_CUT` characters, and
+   * it counts from the guide-first sentence the registry puts in front of every
+   * listed tool. So the rule has to be inside that window of the text A CLIENT
+   * IS HANDED, with the `skillsDir` mechanics — which the guide states in full
+   * anyway — as what a short client loses instead.
+   */
+  it(`states the whole rule within the first ${CLIENT_SHORT_CUT} characters a client is handed`, async () => {
+    for (const layout of [DEFAULT_KB_LAYOUT, { knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' }]) {
+      const { description } = await listedMyPlugin(layout);
+      expect(description.startsWith(`${GUIDE_FIRST_SENTENCE} `), 'the opener is counted too').toBe(true);
+      const cut = description.slice(0, CLIENT_SHORT_CUT);
+      const root = layout.knowledgeBaseDir;
+      for (const phrase of [...RULE, `The knowledge root here is \`${root}/\`.`]) {
+        expect(cut, `"${phrase}" falls past the ${CLIENT_SHORT_CUT}-character cut`).toContain(phrase);
+      }
+    }
+  });
+
+  /**
+   * A folder name may run to 255 bytes. The root is named once, after the rule,
+   * so even the longest name a deployment can choose leaves the whole rule
+   * inside the cut and the whole text inside the cap.
+   */
+  it('keeps the rule inside the cut, and the text inside the cap, for the longest root name', async () => {
+    const longest = { knowledgeBaseDir: 'K'.repeat(255), skillsDir: 'Skills', pluginsDir: 'Plugins' };
+    expect(validateKbLayout(longest), 'the name is one a deployment may choose').toBeNull();
+    const listed = await listedMyPlugin(longest);
+    const cut = listed.description.slice(0, CLIENT_SHORT_CUT);
+    for (const phrase of RULE) {
+      expect(cut, `"${phrase}" falls past the ${CLIENT_SHORT_CUT}-character cut`).toContain(phrase);
+    }
+    expect(listed.description).toContain(`The knowledge root here is \`${longest.knowledgeBaseDir}/\`.`);
+    expect(clientVisibleLength({ name: 'my_plugin', description: listed.description })).toBeLessThanOrEqual(
+      TOOL_DESCRIPTION_CAP,
+    );
+  });
+
+  /** Only the description changed: the call an agent makes is the call it made. */
+  it('keeps its endpoint, inputs, outputs and tags exactly as they were', () => {
+    const def = myPluginDef(DEFAULT_KB_LAYOUT);
+    expect((def.tool_call_template as { url: string; http_method: string }).url).toBe('${API_URL}/api/plugins/personal');
+    expect((def.tool_call_template as { http_method: string }).http_method).toBe('POST');
+    // The flat inputs are wrapped under `body` by `toolDef`; `my_plugin` takes
+    // none, so the envelope is optional too and `my_plugin({})` is a call
+    // that matches (see `bodyEnvelope`).
+    expect(def.inputs).toEqual({
+      type: 'object',
+      properties: { body: { type: 'object', properties: {}, additionalProperties: false } },
+      additionalProperties: false,
+    });
+    expect(Object.keys((def.outputs as { properties: Record<string, unknown> }).properties)).toEqual([
+      'path',
+      'skillsDir',
+      'folder',
+      'name',
+      'displayName',
+      'created',
+    ]);
+    expect(def.tags).toEqual(['plugins', 'skills', 'write']);
+    // Byte-identical on every layout but the description.
+    const renamed = myPluginDef({ knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' });
+    expect({ ...renamed, description: '' }).toEqual({ ...def, description: '' });
+    expect(renamed.description).not.toBe(def.description);
+  });
+
+  /** A layout given with untrimmed names is read the way every other reader reads it. */
+  it('reads the layout through the same resolver the rest of the platform uses', () => {
+    expect(myPluginDescription({ knowledgeBaseDir: '  Docs  ', skillsDir: 'Skills', pluginsDir: 'Plugins' })).toContain(
+      '`Docs/`',
+    );
+  });
+});
+
 describe('the creation endpoints behind the key-or-session gate', () => {
   const ensurePersonalPlugin = vi.fn(async (user: { id: string }) => ({
     folder: `personal-${user.id}`,
@@ -112,7 +263,7 @@ describe('the creation endpoints behind the key-or-session gate', () => {
     expect(createPlugin).toHaveBeenLastCalledWith(expect.objectContaining({ id: ALICE.id }), 'Ops', undefined);
   });
 
-  it("my_plugin's endpoint ensures the caller's own space for a key holder", async () => {
+  it("my_plugin's endpoint ensures the caller's own personal plugin for a key holder", async () => {
     const base = await start();
     const res = await post(base, '/api/plugins/personal', {}, 'bevel_alice');
     expect(res.status).toBe(200);
@@ -129,4 +280,26 @@ describe('the creation endpoints behind the key-or-session gate', () => {
     expect(refused.status).toBe(404);
     expect(await refused.json()).toEqual({ error: 'There is no folder "Nope" under Plugins/.' });
   });
+
+  it('refuses an agent call whose arguments do not match the tool, before anything is provisioned', async () => {
+    // These two routes ARE the tools, so they check a call against what the
+    // tools declare, as every route-hosted tool does. `my_plugin` takes no
+    // arguments; `create_plugin` takes a non-empty `name` and an optional `parent`.
+    myPluginDef(DEFAULT_KB_LAYOUT);
+    const base = await start();
+    const stray = await post(base, '/api/plugins/personal', { unexpected: 1 }, 'bevel_alice');
+    expect(stray.status).toBe(400);
+    const strayBody = (await stray.json()) as { kind: string; error: string };
+    expect(strayBody.kind).toBe('arguments-do-not-match');
+    expect(strayBody.error).toContain('"unexpected" is not an argument of this tool.');
+    expect(strayBody.error.split('\n').pop()).toBe('Call: KNOWLEDGE_BASE.my_plugin({})');
+    expect(ensurePersonalPlugin).not.toHaveBeenCalled();
+
+    const empty = await post(base, '/api/plugins', { name: '' }, 'bevel_alice');
+    expect(empty.status).toBe(400);
+    expect(((await empty.json()) as { error: string }).error).toContain(
+      '"name" must be at least 1 character(s) long, but 0 was given.',
+    );
+    expect(createPlugin).not.toHaveBeenCalled();
+  });
 });

package/src/modules/plugins/index.ts

@@ -4,6 +4,7 @@ export {
   PluginProvisionError,
   pluginAccessMd,
   personalAccessMd,
+  withCreatorGrants,
 } from './plugin-provision.service.js';
 export { JoinRequestsService, type JoinRequest } from './join-requests.service.js';
 export {

package/src/modules/plugins/plugin-provision.service.ts

@@ -151,6 +151,20 @@ export class PluginProvisionService {
    */
   private readonly creations = new WorkspaceMutex();
 
+  /**
+   * Run `fn` holding the creation lock of every plugin name in `names` — for
+   * a writer outside this service that publishes plugins of its own (a
+   * starter pack) and whose name check and commit must be one step against
+   * a creation or a deletion of the same name. The set is taken in one
+   * `runAll`; `fn` must not take this lock again (see `WorkspaceMutex`).
+   */
+  withIdentities<T>(names: string[], fn: () => Promise<T>): Promise<T> {
+    return this.creations.runAll(
+      names.map((name) => `plugin:${pluginManifestName(name)}`),
+      fn,
+    );
+  }
+
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly commits: ProvisionCommitDriver,
@@ -693,7 +707,14 @@ export function personalAccessMd(creator: { name: string; email: string }): stri
   return spliceGrant(seeded, 'read', creatorPrincipal(creator), { allowScalar: false, target: 'node' }).text;
 }
 
-function withCreatorGrants(base: string, creator: { name: string; email: string }): string {
+/**
+ * `base` — an access.md in the two-block shape — with `creator` named under
+ * `read`, `write` and `owner` of the folder: how a plugin made by someone is
+ * run by them. Exported for the one other door that brings a plugin into
+ * being, a starter pack (`modules/onboarding`), whose shipped rules it adds
+ * the admin who applied the pack to.
+ */
+export function withCreatorGrants(base: string, creator: { name: string; email: string }): string {
   const principal = creatorPrincipal(creator);
   let out = base;
   for (const verb of ['read', 'write', 'owner'] as const) {

package/src/modules/plugins/plugins.routes.ts

@@ -16,6 +16,7 @@ import { domainErrorBody } from '../../shared/http-errors.js';
 import { pluginFolderBelowRoot } from './plugins.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { PluginProvisionError, type PluginProvisionService } from './plugin-provision.service.js';
+import { argumentsRefusal } from '../tool-helpers/route-argument-check.js';
 import { PluginLinkError, type PluginLinksService } from './plugin-links.service.js';
 import { PluginRenameError, type PluginRenameService } from './plugin-rename.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
@@ -64,6 +65,24 @@ import type {
  * middleware change can never silently un-gate one. Nothing here is reachable
  * with an agent connection key or a manual-auth bearer.
  */
+/**
+ * Answer the arguments-do-not-match refusal when the body does not match the
+ * tool hosted at this route; `true` when it answered. A body that is not a
+ * JSON object is refused here too, with the sentence `toolHandler` uses, so a
+ * `null` or an array never reaches the handler as if it were `{}`.
+ */
+function refuseMismatchedArguments(req: express.Request, res: express.Response): boolean {
+  const body: unknown = req.body === undefined ? {} : req.body;
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    res.status(400).json({ error: 'Request body must be a JSON object.' });
+    return true;
+  }
+  const mismatch = argumentsRefusal(req.originalUrl, body as Record<string, unknown>, req.query);
+  if (!mismatch) return false;
+  res.status(mismatch.status).json({ ...mismatch.details, error: mismatch.message });
+  return true;
+}
+
 /**
  * The two doors through which plugin folders come to exist — ONE
  * implementation each, for the app and for agents alike:
@@ -96,6 +115,11 @@ export function createPluginCreationRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
+    // These two routes ARE the `create_plugin` and `my_plugin` tools, so an
+    // agent's call is checked against what those tools declare, exactly as a
+    // route-hosted tool's is in `toolHandler`: a call that does not match is
+    // refused before anything is provisioned.
+    if (refuseMismatchedArguments(req, res)) return;
     // `req.body` is undefined when no JSON body was sent at all — that is a
     // 400, not a destructuring crash.
     const { name, parent } = (req.body ?? {}) as { name?: string; parent?: unknown };
@@ -129,6 +153,11 @@ export function createPluginCreationRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
+    // These two routes ARE the `create_plugin` and `my_plugin` tools, so an
+    // agent's call is checked against what those tools declare, exactly as a
+    // route-hosted tool's is in `toolHandler`: a call that does not match is
+    // refused before anything is provisioned.
+    if (refuseMismatchedArguments(req, res)) return;
     try {
       res.json(await provision.ensurePersonalPlugin(user));
     } catch (err) {

package/src/modules/plugins/plugins.tools.ts

@@ -1,3 +1,5 @@
+import { resolveKbLayout, type KbLayout } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
 
@@ -21,9 +23,24 @@ import { toolDef } from '../tool-helpers/tool-def.js';
  * agent exactly as for a person; a refusal comes back as the endpoint's own
  * 4xx with its message.
  */
-export function registerPluginsTools(registry: IToolRegistry): void {
-  registry.registerExternalTool(MY_PLUGIN);
-  registry.registerInternalTool(MY_PLUGIN);
+export function registerPluginsTools(registry: IToolRegistry, kb: KbContext): void {
+  // ONE object on both surfaces, so the rewrite below reaches both of them.
+  // The registry holds this object, and re-registering under the same name
+  // would throw as a duplicate.
+  const myPlugin = myPluginDef(kb.layout);
+  registry.registerExternalTool(myPlugin);
+  registry.registerInternalTool(myPlugin);
+  /**
+   * `my_plugin`'s description NAMES the knowledge root, so its text has to
+   * follow the layout: the save that completes first-run setup applies the
+   * names the admin just chose in that same request, without a restart, and a
+   * description built once at registration would go on sending notes to a
+   * folder this deployment no longer has. Rewritten in place, exactly as the
+   * workspace tools' descriptions are (see `workspace.tools.ts`).
+   */
+  kb.onLayoutApplied(() => {
+    myPlugin.description = myPluginDescription(kb.layout);
+  });
   registry.registerExternalTool(CREATE_PLUGIN);
   registry.registerInternalTool(CREATE_PLUGIN);
 }
@@ -41,21 +58,64 @@ const PROVISIONED_OUTPUT = {
   },
 } as const;
 
-export const MY_PLUGIN: UtcpTool = toolDef({
-  name: 'my_plugin',
-  description:
-    "The caller's own private plugin — their personal space in the knowledge base, created on first use. " +
+/**
+ * What an agent reads about the personal plugin, for the layout in effect.
+ *
+ * THE RULE COMES FIRST, and the order is the substance of it rather than a
+ * matter of style. A personal plugin holds its owner's skills and tools;
+ * nothing under the plugins root is part of the knowledge graph, and a
+ * personal plugin is readable only by its owner — so a note filed there is
+ * never found as knowledge again, by anyone, including its author's next
+ * agent. Agents asked to "save this for me" were reading the old opening,
+ * "their personal space in the knowledge base", as an invitation to do
+ * precisely that.
+ *
+ * Stated ahead of the mechanics of writing a skill, not after them, because
+ * claude.ai cuts a tool description near `CLIENT_SHORT_CUT` characters (see
+ * `tool-registry/description-length.ts`) counted from the guide-first sentence
+ * the registry puts in front of every listed tool. What survives that cut is
+ * decided by ORDER, so the rule sits inside it and the `skillsDir` detail —
+ * which the guide states in full anyway — is what a short client loses.
+ * The root is named ONCE, after the rule rather than inside it: a folder name
+ * may run to 255 bytes, and repeated within the rule it could push the rule
+ * itself past the cut and the whole text past `TOOL_DESCRIPTION_CAP`.
+ * `plugins.tools.test.ts` pins that placement rather than trusting this note.
+ *
+ * It REFUSES nothing. The write gate accepts every file in a personal plugin
+ * exactly as it did before; this text is the whole of the change.
+ */
+export function myPluginDescription(layout: KbLayout): string {
+  const knowledge = `\`${resolveKbLayout(layout).knowledgeBaseDir}/\``;
+  return (
+    "The caller's personal plugin: their own skills and tools, created on first use. " +
+    'Notes, knowledge and other documents do NOT go here; they go under the knowledge root. ' +
+    'For something the user wants kept private, ask where under the knowledge root it should go and say a ' +
+    'folder there can be restricted so only they can read it; never write it here, even if asked. ' +
+    `The knowledge root here is ${knowledge}. ` +
     'Returns its folder and where skills go inside it (`skillsDir`); write a skill there as ' +
     '`<skillsDir>/<skill-name>/SKILL.md` with the file tools, opening with the Agent Skills frontmatter ' +
     '(`name`, `description`, and `metadata.version` such as `"1.0.0"`). Readable only by its owner — not even admins — and ' +
-    'never listed as a shared plugin. Idempotent: calling it again returns the same folder.',
-  path: '/api/plugins/personal',
-  inputs: { type: 'object', properties: {}, additionalProperties: false },
-  outputs: PROVISIONED_OUTPUT,
-  // `write`: both make folders and commit — a read-scoped caller's manual
-  // must not advertise them (see `isWriteTool` in the manual routes).
-  tags: ['plugins', 'skills', 'write'],
-});
+    'never listed as a shared plugin. Idempotent: calling it again returns the same folder.'
+  );
+}
+
+/**
+ * The `my_plugin` definition for `layout`. Everything but the description is
+ * the same on every deployment and byte-identical to what it has always been:
+ * the same endpoint, the same (empty) inputs, the same outputs, the same tags.
+ */
+export function myPluginDef(layout: KbLayout): UtcpTool {
+  return toolDef({
+    name: 'my_plugin',
+    description: myPluginDescription(layout),
+    path: '/api/plugins/personal',
+    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    outputs: PROVISIONED_OUTPUT,
+    // `write`: both make folders and commit — a read-scoped caller's manual
+    // must not advertise them (see `isWriteTool` in the manual routes).
+    tags: ['plugins', 'skills', 'write'],
+  });
+}
 
 export const CREATE_PLUGIN: UtcpTool = toolDef({
   name: 'create_plugin',