@bevel-software/platform-core-backend 0.14.0 → 0.19.0

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

@@ -25,24 +25,31 @@
  *     reads `everyone` — anyone may open the FILE, see the plugin listed, and
  *     ask to join — while the BODY (the folder's actual rules) names only
  *     the creator under read, write and owner.
- *   - A PERSONAL folder (`personal-<user-id>`): private by design. No
- *     frontmatter grant at all, so nobody else can even see it exists; the
- *     body names its owner. Created lazily (ensure semantics) on the first
- *     personal skill.
+ *   - A PERSONAL folder (`personal-<user-id>`): private by design, in both
+ *     blocks. The frontmatter denies `everyone` and names only the owner,
+ *     so nobody else can even see it exists; the body says the same of the
+ *     folder. Created lazily (ensure semantics) on the first personal skill.
  */
 
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import type { IFsProbe } from '../../shared/fs.contract.js';
+import type { Discovery, PluginSource } from './discovery/plugin-source.js';
 
 import {
   DEFAULT_BRANCH,
   PLUGINS_DIR,
   PLUGIN_MANIFEST_FILE,
+  PLUGIN_SKILLS_DIR,
+  pluginDisplayNameOf,
   pluginManifestName,
   renderPluginManifest,
   PERSONAL_PLUGIN_PREFIX,
+  isPersonalPluginDir,
   isPersonalPluginFolder,
   personalPluginFolderName,
+  validateFilename,
   type AuthUser,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
@@ -62,9 +69,50 @@ export interface ProvisionCommitDriver {
   ): Promise<void>;
 }
 
+/**
+ * A directory's entries, or null when there is no such directory. ONLY
+ * absence reads as "nothing there": a listing that fails for any other
+ * reason (permissions, I/O) throws, because "the folder is not there" and
+ * "the folder could not be read" must never collapse into one answer — the
+ * first is a 404 to a caller, the second an outage an operator must see.
+ */
+async function listDirOrIncomplete(
+  disk: IFsProbe,
+  dir: string,
+  repoRel: string,
+): Promise<Array<{ name: string; isDirectory(): boolean }> | null> {
+  try {
+    return await disk.listDir(dir);
+  } catch {
+    // The same refusal a hole in discovery gets: this listing is one more
+    // read the operation needed and could not have.
+    throw incompleteDiscovery([repoRel]);
+  }
+}
+
+/** The refusal for a discovery with a hole in it: a name cannot be checked, an identity cannot be known. */
+function incompleteDiscovery(unreadable: string[]): PluginProvisionError {
+  return new PluginProvisionError(
+    `Some of the knowledge base could not be read (${unreadable.join(', ')}), so the plugin cannot be checked against every other. Try again, or ask an admin.`,
+    503,
+  );
+}
+
 export interface ProvisionedPlugin {
-  /** The folder name under `Plugins/` (not the full path). */
+  /** The folder's path below `Plugins/` — `GTM`, or `Teams/GTM` for one made inside a grouping folder. */
   folder: string;
+  /** The same folder, repo-relative — `Plugins/Teams/GTM` — as the file tools address it. */
+  path: string;
+  /** Where its skills go: `<path>/skills`, each skill a subfolder holding a `SKILL.md`. */
+  skillsDir: string;
+  /** The plugin's identity — the manifest name written for it. */
+  name: string;
+  /**
+   * What a person sees it called — the manifest's `displayName`, which is the
+   * name the creator typed, trimmed. Exactly as persisted: the answer and the
+   * file on disk can never say two different things.
+   */
+  displayName: string;
   /** False when an ensure found the folder already there. */
   created: boolean;
 }
@@ -80,6 +128,12 @@ export class PluginProvisionError extends Error {
   }
 }
 
+/** The one shape every provisioning answer has: the folder in both spellings, and where its skills go. */
+function provisioned(folder: string, name: string, displayName: string, created: boolean): ProvisionedPlugin {
+  const path = `${PLUGINS_DIR}/${folder}`;
+  return { folder, path, skillsDir: `${path}/${PLUGIN_SKILLS_DIR}`, name, displayName, created };
+}
+
 export class PluginProvisionService {
   /**
    * Serialises creations and deletions by MANIFEST SLUG
@@ -96,21 +150,31 @@ export class PluginProvisionService {
     private readonly commits: ProvisionCommitDriver,
     private readonly accessControl: IAccessControl,
     private readonly kbDirName: string,
-    private readonly events?: { emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void },
+    private readonly events: { emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void } | undefined,
+    /** Which names are TAKEN is discovery's answer — the same one every catalog gets. */
+    private readonly source: PluginSource,
+    private readonly disk: IFsProbe,
   ) {}
 
   /**
-   * Create `Plugins/<name>/` for `user`. Throws `PluginProvisionError` 422 on a
-   * name the filesystem or the model cannot carry, 409 when the name is taken
-   * (case-insensitively — the workspaces live on case-insensitive
-   * filesystems too, where `GTM` and `gtm` are one folder).
+   * Create `Plugins/<name>/` — or `Plugins/<parent>/<name>/` — for `user`.
+   * Throws `PluginProvisionError` 422 on a name the filesystem or the model
+   * cannot carry, 409 when the name is taken (case-insensitively — the
+   * workspaces live on case-insensitive filesystems too, where `GTM` and
+   * `gtm` are one folder), 404 when `parent` names no folder.
+   *
+   * `parent` is a GROUPING folder below the plugins root (`Teams`,
+   * `Teams/EU`): it must exist, and it must not be a plugin or sit inside
+   * one — discovery claims a plugin's whole subtree, so a plugin made there
+   * would be invisible to every catalog. The identity checks are the same at
+   * any depth: a nested plugin claims its slug as fully as a top-level one.
    */
-  async createPlugin(user: AuthUser, rawName: string): Promise<ProvisionedPlugin> {
+  async createPlugin(user: AuthUser, rawName: string, rawParent?: string): Promise<ProvisionedPlugin> {
     const name = rawName.trim();
     if (!name) throw new PluginProvisionError('A plugin needs a name.', 422);
-    // eslint-disable-next-line no-control-regex -- NUL and control chars are
-    // exactly what a filesystem path cannot carry; refusing them here keeps
-    // the refusal a 422 instead of the fs layer's 500.
+    // NUL and control chars are exactly what a filesystem path cannot carry;
+    // refusing them here keeps the refusal a 422 instead of the fs layer's 500.
+    // eslint-disable-next-line no-control-regex
     if (/[/\\\u0000-\u001f\u007f]/.test(name) || name === '.' || name === '..' || name.startsWith('.')) {
       throw new PluginProvisionError(
         'A plugin name can\'t contain / or \\ or control characters, or start with a dot.',
@@ -131,6 +195,9 @@ export class PluginProvisionService {
         422,
       );
     }
+    // The name is judged before the parent: a name that can never be created
+    // is refused as such, not as "no such folder" or "discovery incomplete".
+    const parent = await this.resolveParent(rawParent);
     // Locked on the manifest SLUG, not the lowercased folder: the slug is the
     // identity the twin check below defends, and two spellings that collide
     // on it ("Sales Team" / "Sales-Team") must take the SAME lock or both
@@ -138,7 +205,7 @@ export class PluginProvisionService {
     // key subsumes the old lowercase one — and deletion (below) derives its
     // key the same way, keeping delete/re-create of one name serialized.
     return this.creations.run(`plugin:${pluginManifestName(name)}`, async () => {
-      const existing = await this.existingFolder(name);
+      const existing = await this.existingFolder(name, parent);
       if (existing !== null) {
         throw new PluginProvisionError(`A plugin named "${existing}" already exists.`, 409);
       }
@@ -155,33 +222,85 @@ export class PluginProvisionService {
           409,
         );
       }
-      await this.provision(user, name, pluginAccessMd(user));
-      return { folder: name, created: true };
+      const folder = parent ? `${parent}/${name}` : name;
+      // `name` is the creator's own spelling, trimmed — the folder's leaf AND
+      // the display name persisted for it, whether or not it equals either.
+      await this.provision(user, folder, name, pluginAccessMd(user));
+      return provisioned(folder, pluginManifestName(name), name, true);
     });
   }
 
+  /**
+   * The grouping folder a creation goes into, as its path below the plugins
+   * root — `''` for the root itself. Validated AS GIVEN, segment by segment,
+   * with the one rule every path here obeys (`validateFilename`, no
+   * dot-prefix); it must exist with every component spelled as on disk; and
+   * it must be a GROUPING folder — not a personal space, not a plugin, not
+   * inside one, since discovery claims a plugin's subtree and a plugin made
+   * there would be listed nowhere. A hole in discovery refuses, as for every
+   * other provisioning write.
+   */
+  private async resolveParent(rawParent: string | undefined): Promise<string> {
+    if (rawParent === undefined || rawParent === '') return '';
+    const segments = rawParent.split('/');
+    if (segments.some((s) => validateFilename(s) !== null || s.startsWith('.'))) {
+      throw new PluginProvisionError(`"${rawParent}" is not a folder name the knowledge base can carry.`, 422);
+    }
+    const rel = `${PLUGINS_DIR}/${rawParent}`;
+    // The personal namespace is the FIRST segment below the root — the same
+    // structural rule as `isPersonalPluginDir`, applied to the parent and
+    // everything under it. A `personal-*` folder there is a personal space
+    // whether it was provisioned yet or not: the prefix is reserved at that
+    // depth (creation refuses the slug, rename refuses the name).
+    if (isPersonalPluginFolder(segments[0]!)) {
+      throw new PluginProvisionError('A plugin cannot be made inside a personal space.', 422);
+    }
+    const wsId = await this.readyWorkspaceId();
+    const wsDir = await this.workspaceService.getWorkspacePath(wsId);
+    if (!(await this.exactFolderExists(path.join(wsDir, this.kbDirName, PLUGINS_DIR), segments))) {
+      throw new PluginProvisionError(`There is no folder "${rawParent}" under ${PLUGINS_DIR}/.`, 404);
+    }
+    // Judged against every folder discovery CLAIMS, not only the plugins it
+    // lists: a twin skipped for its slug still owns its subtree, and a
+    // plugin made in there would be listed by no catalog.
+    const { claimed, unreadable } = await this.discovered();
+    if (unreadable.length > 0) throw incompleteDiscovery(unreadable);
+    const inside = claimed.find((c) => rel === c || rel.startsWith(`${c}/`));
+    if (inside) {
+      throw new PluginProvisionError(
+        `"${rawParent}" is inside the plugin at ${inside} — a plugin cannot hold another plugin.`,
+        422,
+      );
+    }
+    return rawParent;
+  }
+
   /**
    * Ensure the caller's personal folder exists — idempotent, keyed to the
-   * stable user id. Returns `created: false` when it is already there.
+   * stable user id. Returns `created: false` when it is already there, and
+   * with it the display name the existing manifest carries (see
+   * {@link persistedDisplayName}): the answer is what the file says, so the
+   * call that made the folder and every call after it agree.
    */
   async ensurePersonalPlugin(user: AuthUser): Promise<ProvisionedPlugin> {
     const folder = personalPluginFolderName(user.id);
     return this.creations.run(`plugin:${pluginManifestName(folder)}`, async () => {
-      if ((await this.existingFolder(folder)) !== null) {
-        return { folder, created: false };
+      const existing = await this.existingFolder(folder);
+      if (existing !== null) {
+        return provisioned(folder, pluginManifestName(folder), await this.persistedDisplayName(existing, folder), false);
       }
       try {
-        await this.provision(user, folder, personalAccessMd(user));
+        await this.provision(user, folder, folder, personalAccessMd(user));
       } catch (err) {
         // ENSURE semantics even under a race the lock cannot see (another
         // process, a checkout that appeared between check and write): the
         // folder existing is this method's success case, never its error.
         if (err instanceof PluginProvisionError && err.status === 409) {
-          return { folder, created: false };
+          return provisioned(folder, pluginManifestName(folder), await this.persistedDisplayName(folder, folder), false);
         }
         throw err;
       }
-      return { folder, created: true };
+      return provisioned(folder, pluginManifestName(folder), folder, true);
     });
   }
 
@@ -204,29 +323,64 @@ export class PluginProvisionService {
    * never interleave with a re-creation of the same name (the key derives
    * from the name, so both spell it identically).
    */
-  async deletePlugin(user: AuthUser, rawName: string): Promise<void> {
-    const name = rawName.trim();
-    if (!name) throw new PluginProvisionError('A plugin needs a name.', 422);
-    if (isPersonalPluginFolder(name)) {
+  async deletePlugin(user: AuthUser, rawFolder: string): Promise<void> {
+    // The folder's path BELOW the plugins root — `GTM`, or `teams/deep` for a
+    // plugin nested where discovery found it. Segments only: nothing that
+    // could climb out of the root, and no backslash — `/` is the one
+    // separator the repository speaks, and a `\` would read as a second one
+    // on Windows and as a name character everywhere else.
+    // Validated AS GIVEN, never trimmed first: a folder spelled with a
+    // leading or trailing space names no folder the catalog handed out, and
+    // trimming it would delete a different one. (`validateFilename` refuses
+    // the whitespace.)
+    const name = rawFolder;
+    const segments = name.split('/');
+    // Every segment must be a name the filesystem carries (the ONE rule
+    // creation applies, `validateFilename`: no control characters, no `\`,
+    // no `.`/`..`, no reserved names) and none may be dot-prefixed (a parked
+    // delete, invisible to every scanner) — refused here as a 422, never
+    // discovered by the fs layer as a 500.
+    if (!name || segments.some((s) => validateFilename(s) !== null || s.startsWith('.'))) {
+      throw new PluginProvisionError('A plugin needs a name.', 422);
+    }
+    if (isPersonalPluginDir(`${PLUGINS_DIR}/${name}`)) {
       // Personal folders are not plugins (the catalog never lists them), and
       // nobody deletes somebody's private shelf through the plugin door.
       throw new PluginProvisionError('Unknown plugin', 404);
     }
-    return this.creations.run(`plugin:${pluginManifestName(name)}`, async () => {
-      const existing = await this.existingFolder(name);
-      // Exact match only — the catalog hands the route the on-disk casing,
-      // so a mismatch means the plugin is gone (or was never there).
-      if (existing !== name) throw new PluginProvisionError('Unknown plugin', 404);
+    const wsId = await this.readyWorkspaceId();
+    const wsDir = await this.workspaceService.getWorkspacePath(wsId);
+    const pluginsDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR);
+    const folderDir = path.join(pluginsDir, ...segments);
+    // Locked on the plugin's IDENTITY — the same key a creation of that name
+    // takes — not on a slug of the folder path, which for a nested plugin is a
+    // different string and would let a creation of the same identity run
+    // inside the delete's window. The identity is DISCOVERY's answer, in
+    // either file shape (a bundle's name as much as a manifest's), so delete
+    // and create can never key on two spellings of one plugin; a hole in
+    // discovery refuses, as it does for creation. A folder discovery does not
+    // list (no manifest at all) locks on its own slug — nothing else can
+    // claim that identity either.
+    const identity = await this.discoveredIdentity(`${PLUGINS_DIR}/${name}`, segments[segments.length - 1]!);
+    return this.creations.run(`plugin:${identity}`, async () => {
+      // Exact spelling of EVERY component — the catalog hands the route the
+      // on-disk spelling, so a mismatch means the plugin is gone (or was
+      // never there). Checked against directory listings, never `stat`: on a
+      // case-insensitive filesystem a stale spelling would stat a replacement
+      // plugin at the same location and park THAT.
+      if (!(await this.exactFolderExists(pluginsDir, segments))) {
+        throw new PluginProvisionError('Unknown plugin', 404);
+      }
 
-      const wsId = await this.readyWorkspaceId();
-      const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-      const pluginsDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR);
-      const folderDir = path.join(pluginsDir, name);
       // Dot-prefixed ⇒ invisible to the plugin scanner and the collision
-      // check for the whole window the commit is in flight.
-      const parkedDir = path.join(pluginsDir, `.${name}.deleting`);
-
-      await fs.rm(parkedDir, { recursive: true, force: true }); // a stale park from a crashed run
+      // check for the whole window the commit is in flight. UNIQUE, so the
+      // park never lands on — and never removes — a path that was already
+      // there: a sibling somebody named that way, or the residue of a run
+      // that crashed mid-delete (which stays, invisible, for a person to
+      // clear; a delete must never destroy anything but the plugin it names).
+      // FIXED LENGTH: the plugin's own name is not part of it, so a name near
+      // the filesystem's component limit parks as well as a short one.
+      const parkedDir = path.join(path.dirname(folderDir), `.deleting-${randomUUID()}`);
       await fs.rename(folderDir, parkedDir);
       try {
         // Inline and `systemAuthorized`, for `provision`'s reasons in
@@ -261,48 +415,108 @@ export class PluginProvisionService {
     });
   }
 
-  /** The taken name (in its on-disk casing) colliding with `name`, or null. */
-  private async existingFolder(name: string): Promise<string | null> {
+  /**
+   * Whether `segments` names a directory below `root` with every component
+   * spelled exactly as on disk — by listing each level, which is the one
+   * question a case-insensitive filesystem answers honestly.
+   */
+  private async exactFolderExists(root: string, segments: string[]): Promise<boolean> {
+    let dir = root;
+    let rel = PLUGINS_DIR;
+    for (const segment of segments) {
+      const entries = await listDirOrIncomplete(this.disk, dir, rel);
+      if (!entries?.some((e) => e.isDirectory() && e.name === segment)) return false;
+      dir = path.join(dir, segment);
+      rel = `${rel}/${segment}`;
+    }
+    return true;
+  }
+
+  /**
+   * The taken name (in its on-disk casing) colliding with `name` in `parent`
+   * (`''` = the plugins root), or null.
+   */
+  private async existingFolder(name: string, parent = ''): Promise<string | null> {
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    let children: string[];
-    try {
-      children = await fs.readdir(path.join(wsDir, this.kbDirName, PLUGINS_DIR));
-    } catch {
-      return null; // no Plugins/ root yet — nothing can collide
-    }
+    const rel = parent ? `${PLUGINS_DIR}/${parent}` : PLUGINS_DIR;
+    // No Plugins/ root yet — nothing can collide.
+    const children = await listDirOrIncomplete(this.disk, path.join(wsDir, this.kbDirName, rel), rel);
+    if (!children) return null;
     const lower = name.toLowerCase();
-    return children.find((c) => c.toLowerCase() === lower) ?? null;
+    return children.find((c) => c.name.toLowerCase() === lower)?.name ?? null;
   }
 
-  /** An existing PLUGIN FOLDER whose derived manifest name equals `name`'s, or null. */
-  private async manifestNameTwin(name: string): Promise<string | null> {
+  /**
+   * What the plugin at `folder` is ALREADY called, read from its manifest by
+   * the one shared rule — `fallback` only when there is no manifest to read
+   * (a folder mid-creation, a `plugin.json` that is not an object).
+   *
+   * An ensure that found the folder already there answers with the FILE's
+   * answer, never the folder's spelling: the folder is an input to no name,
+   * and an idempotent call whose second answer differed from its first would
+   * be this service telling the caller a plugin had been renamed.
+   */
+  private async persistedDisplayName(folder: string, fallback: string): Promise<string> {
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    let children: Array<{ name: string; isDirectory(): boolean }>;
-    try {
-      children = await fs.readdir(path.join(wsDir, this.kbDirName, PLUGINS_DIR), {
-        withFileTypes: true,
-      });
-    } catch {
-      return null; // no Plugins/ root yet — nothing can collide
-    }
-    const slug = pluginManifestName(name);
-    // Only what actually publishes a manifest claims a slug: a DIRECTORY
-    // that is not dot-prefixed (a parked delete — invisible to every
-    // scanner). Personal folders count — they publish a plugin.json like
-    // any plugin (though the reservation above means a named plugin can
-    // never reach this check with a personal slug). A loose file at the
-    // root (`Plugins/slack.tool`) is not a plugin and must not 409 a
-    // legitimate "Slack Tool".
-    return (
-      children.find(
-        (c) => c.isDirectory() && !c.name.startsWith('.') && pluginManifestName(c.name) === slug,
-      )?.name ?? null
+    const manifest = await this.disk.readJsonObject(
+      path.join(wsDir, this.kbDirName, PLUGINS_DIR, ...folder.split('/'), PLUGIN_MANIFEST_FILE),
     );
+    return pluginDisplayNameOf(manifest) || fallback;
   }
 
-  private async provision(user: AuthUser, folder: string, accessMd: string): Promise<void> {
+  /**
+   * The identity discovery gives the plugin at `folder`, or the folder's own
+   * slug when it lists none there. ONE rule for every write provisioning
+   * makes — create, delete — as for the rename: no write over a discovery
+   * with a hole in it, whether or not the hole is where this plugin lives.
+   * An operation that parks and commits against an identity set it could
+   * not fully see is the class of mistake the rule exists to make impossible.
+   */
+  private async discoveredIdentity(folder: string, leaf: string): Promise<string> {
+    const { plugins, unreadable } = await this.discovered();
+    if (unreadable.length > 0) throw incompleteDiscovery(unreadable);
+    const found = plugins.find((p) => p.folder === folder);
+    // The lock key is the SLUG — what the marketplace publishes and what a
+    // creation of the name locks on — so a bundle declaring "Sales Team"
+    // and a creation of `sales-team` take one lock. Not listed and nothing
+    // unreadable: no manifest, no bundle — the folder is its own identity.
+    return pluginManifestName(found ? found.name : leaf);
+  }
+
+  /** One discovery over the knowledge base checkout. */
+  private async discovered(): Promise<Discovery> {
+    const wsId = await this.readyWorkspaceId();
+    const wsDir = await this.workspaceService.getWorkspacePath(wsId);
+    return this.source.discover(path.join(wsDir, this.kbDirName));
+  }
+
+  /**
+   * An existing plugin — at ANY depth, in either file shape — whose identity
+   * folds to the same slug as `name`'s, as its repo-relative folder; or null.
+   * Discovery's answer, so creation and every catalog agree on what is taken:
+   * a nested plugin claims its identity as fully as a top-level one, and a
+   * parked delete (dot-prefixed, invisible to the walk) claims nothing.
+   * Personal folders count — they publish a plugin.json like any plugin
+   * (though the reservation above means a named plugin never reaches this
+   * check with a personal slug). A loose file at the root is not a plugin.
+   *
+   * Refuses on a HOLE: a listing that could not see part of the tree cannot
+   * prove a name free.
+   */
+  private async manifestNameTwin(name: string): Promise<string | null> {
+    const { plugins, unreadable } = await this.discovered();
+    if (unreadable.length > 0) throw incompleteDiscovery(unreadable);
+    const slug = pluginManifestName(name);
+    return plugins.find((p) => pluginManifestName(p.name) === slug)?.folder ?? null;
+  }
+
+  /**
+   * Seed `Plugins/<folder>/` — `folder` being the path below the root, `leaf`
+   * its last segment, which names the manifest — and commit it.
+   */
+  private async provision(user: AuthUser, folder: string, leaf: string, accessMd: string): Promise<void> {
     const wsId = await this.readyWorkspaceId();
     const folderPath = `${this.kbDirName}/${PLUGINS_DIR}/${folder}`;
     const wsRelPath = `${folderPath}/access.md`;
@@ -323,10 +537,17 @@ export class PluginProvisionService {
       // this app, so it lands in the same commit as the access rules — and
       // INSIDE the rollback scope: a manifest write that fails must clean up
       // the access.md it would otherwise strand as a half-made plugin.
+      //
+      // `leaf` is the name its creator typed, trimmed — the folder's last
+      // segment and, as the renderer's `displayName`, what people will see it
+      // called, persisted whether or not it equals the identifier the name
+      // folds to. Every door into here (the dialog's route, the
+      // `create_plugin` tool, the personal-folder ensure) arrives through
+      // this one write, so no two of them can derive a different name.
       await this.workspaceService.writeFile(
         wsId,
         `${folderPath}/${PLUGIN_MANIFEST_FILE}`,
-        renderPluginManifest(folder),
+        renderPluginManifest(leaf),
       );
       // Inline, not enqueued: the gate reads rules at HEAD, so the folder is
       // only real once this commit lands. `runPendingCommit` is the same
@@ -374,18 +595,75 @@ export class PluginProvisionService {
  * (body read/write/owner name the creator). The `read: []` placeholder makes
  * the body parse as rules from the first byte, so every later splice targets
  * the body rather than the frontmatter.
+ *
+ * The comments are part of the template on purpose. The file is what an
+ * administrator opens to widen a plugin, and the two blocks look alike: a
+ * person who finds `everyone` already under the top `read:` and adds nothing
+ * concludes that "everyone" does nothing. Each block says what it governs,
+ * and the body says how to admit people, right where they would type it.
+ * `spliceGrant` preserves comments, so every later edit keeps them.
  */
 export function pluginAccessMd(creator: { name: string; email: string }): string {
-  return withCreatorGrants('---\nread:\n  - everyone\n---\nread: []\n', creator);
+  return withCreatorGrants(
+    [
+      '---',
+      '# THIS BLOCK (the frontmatter) governs this access.md FILE only: who may',
+      '# see it and who may change it. `read: everyone` here means every signed-in',
+      '# person can see that the plugin exists and ask to join. It admits nobody.',
+      'read:',
+      '  - everyone',
+      '---',
+      '# THIS BLOCK (the body) governs the PLUGIN FOLDER — its skills, tools and',
+      '# manifest. To admit people, add them under `read:` (use it) or `write:`',
+      '# (change it): a role from roles.yaml, a group from groups.yaml, or a person',
+      '# as `Name <email>`. `everyone` under `read:` HERE opens the plugin to all',
+      '# signed-in users. Keep this block pure YAML; explanations go in `#` lines.',
+      'read: []',
+      '',
+    ].join('\n'),
+    creator,
+  );
 }
 
 /**
- * A personal folder's access.md: PRIVATE — no frontmatter grant, so the
- * folder is invisible to everyone but its owner; the body names the owner
- * under read, write and owner.
+ * A personal folder's access.md: PRIVATE, in both blocks. The body DENIES
+ * `everyone` read outright, so a `read: everyone` an administrator later
+ * adds at the repo root (the usual way to open the knowledge base up) cannot
+ * open every person's private space with it, and names the owner directly,
+ * which outranks the denial. The frontmatter says the same of the FILE — so
+ * the folder's listing is invisible to everyone but the owner, and so the
+ * file states its own privacy where a reader (and the Library's "Private"
+ * mark, see `isPrivateAccessMd`) looks for it, rather than leaving it to
+ * what an empty block happens to inherit. Nobody else is named — not even
+ * Admin: a private space is private from the people who run the deployment
+ * too. (An administrator can still write this file, through the resolver's
+ * access.md rescue, and so grant themselves in; that is a visible act in
+ * the history, not a default.)
+ *
+ * The frontmatter is also what marks the file as body-governed. Without it
+ * the splicer (and the resolver) read the older single-block format, where
+ * the frontmatter IS the folder's rules.
  */
 export function personalAccessMd(creator: { name: string; email: string }): string {
-  return withCreatorGrants('read: []\n', creator);
+  const seeded = withCreatorGrants(
+    [
+      '---',
+      '# THIS BLOCK (the frontmatter) governs this access.md FILE only. Only the',
+      '# owner is named: a personal space is not listed for anyone else.',
+      'read:',
+      '  - deny everyone',
+      '---',
+      '# THIS BLOCK (the body) governs the FOLDER — one person\'s private space.',
+      '# `deny everyone` keeps it closed even when the repository root grants',
+      '# `read: everyone`; only the owner is named — not even Admin reads it.',
+      '# To share it, add a person as `Name <email>` or a role under `read:`.',
+      'read:',
+      '  - deny everyone',
+      '',
+    ].join('\n'),
+    creator,
+  );
+  return spliceGrant(seeded, 'read', creatorPrincipal(creator), { allowScalar: false, target: 'node' }).text;
 }
 
 function withCreatorGrants(base: string, creator: { name: string; email: string }): string {