@bevel-software/platform-core-backend 0.15.1 → 0.20.0

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

@@ -25,27 +25,29 @@
  *     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 { isAbsence } from '../../shared/fs-errors.js';
+import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { Discovery, PluginSource } from './discovery/plugin-source.js';
-import { KbPluginSource } from './discovery/kb-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,
@@ -75,13 +77,13 @@ export interface ProvisionCommitDriver {
  * 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 fs.readdir(dir, { withFileTypes: true });
-  } catch (err) {
-    if (isAbsence(err)) return null;
+    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]);
@@ -97,10 +99,20 @@ function incompleteDiscovery(unreadable: string[]): PluginProvisionError {
 }
 
 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;
 }
@@ -116,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
@@ -132,18 +150,26 @@ 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 = new KbPluginSource(),
+    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);
     // NUL and control chars are exactly what a filesystem path cannot carry;
@@ -169,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
@@ -176,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);
       }
@@ -193,33 +222,85 @@ export class PluginProvisionService {
           409,
         );
       }
-      await this.provision(user, name, pluginAccessMd(user));
-      return { folder: name, name: pluginManifestName(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, name: pluginManifestName(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, name: pluginManifestName(folder), created: false };
+          return provisioned(folder, pluginManifestName(folder), await this.persistedDisplayName(folder, folder), false);
         }
         throw err;
       }
-      return { folder, name: pluginManifestName(folder), created: true };
+      return provisioned(folder, pluginManifestName(folder), folder, true);
     });
   }
 
@@ -343,7 +424,7 @@ export class PluginProvisionService {
     let dir = root;
     let rel = PLUGINS_DIR;
     for (const segment of segments) {
-      const entries = await listDirOrIncomplete(dir, rel);
+      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}`;
@@ -351,17 +432,40 @@ export class PluginProvisionService {
     return true;
   }
 
-  /** The taken name (in its on-disk casing) colliding with `name`, or null. */
-  private async existingFolder(name: string): Promise<string | null> {
+  /**
+   * 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);
+    const rel = parent ? `${PLUGINS_DIR}/${parent}` : PLUGINS_DIR;
     // No Plugins/ root yet — nothing can collide.
-    const children = await listDirOrIncomplete(path.join(wsDir, this.kbDirName, PLUGINS_DIR), PLUGINS_DIR);
+    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.name.toLowerCase() === lower)?.name ?? 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);
+    const manifest = await this.disk.readJsonObject(
+      path.join(wsDir, this.kbDirName, PLUGINS_DIR, ...folder.split('/'), PLUGIN_MANIFEST_FILE),
+    );
+    return pluginDisplayNameOf(manifest) || fallback;
+  }
+
   /**
    * 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
@@ -408,7 +512,11 @@ export class PluginProvisionService {
     return plugins.find((p) => pluginManifestName(p.name) === slug)?.folder ?? null;
   }
 
-  private async provision(user: AuthUser, folder: string, accessMd: string): Promise<void> {
+  /**
+   * 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`;
@@ -429,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
@@ -480,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 {

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

@@ -9,7 +9,7 @@ import {
 } from '@bevel-software/platform-shared';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
-import { walkKb, type KbWalkListener } from '../../shared/kb-walk.js';
+import type { ITreeWalker, WalkListener } from '../../shared/fs.contract.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import {
   PLUGIN_TOKEN_PREFIX,
@@ -69,6 +69,7 @@ export class PluginRenameService {
     private readonly commits: RenameCommitDriver,
     private readonly accessControl: IAccessControl,
     private readonly source: PluginSource,
+    private readonly disk: ITreeWalker,
     private readonly kbDirName: string,
     private readonly events?: {
       emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void;
@@ -103,14 +104,14 @@ export class PluginRenameService {
     // happens here — no file is read, nothing is decided — so it can run
     // before authorization without telling anyone anything.
     const grantFiles: string[] = [];
-    const grantListener: KbWalkListener = {
+    const grantListener: WalkListener = {
       onFile(dir, name) {
         if (hasAccessFrontmatterExtension(name)) grantFiles.push(dir ? `${dir}/${name}` : name);
       },
     };
     const { discovery, holes } = this.source.walkWith
       ? await this.source.walkWith(kbRoot, [grantListener])
-      : { discovery: await this.source.discover(kbRoot), holes: (await walkKb(kbRoot, [grantListener])).holes };
+      : { discovery: await this.source.discover(kbRoot), holes: (await this.disk.walkKb(kbRoot, [grantListener])).holes };
     const { plugins } = discovery;
     const unreadable = [...new Set([...discovery.unreadable, ...holes])];
     // Three phases: READ everything, DECIDE, then WRITE. Nothing about the
@@ -165,14 +166,23 @@ export class PluginRenameService {
     if (identifierChanges && plugins.some((p) => p !== plugin && pluginManifestName(p.name) === nextName)) {
       throw new PluginRenameError(`A plugin named "${nextName}" already exists.`, 409, { kind: 'name-taken' });
     }
-    const folderName = path.posix.basename(plugin.folder);
+    // What the MANIFEST says today, not what discovery resolved: a manifest
+    // carrying no `displayName` shows its identifier, and carrying THAT over
+    // an identifier change would persist the name the plugin just stopped
+    // being called. The stored field is the only thing an untouched display
+    // name can mean.
+    const storedDisplay =
+      typeof plugin.manifest?.displayName === 'string' ? plugin.manifest.displayName.trim() : '';
     const nextDisplay =
-      patch.displayName === undefined ? plugin.displayName : String(patch.displayName).trim();
+      patch.displayName === undefined ? storedDisplay : String(patch.displayName).trim();
 
-    // The manifest, with everything else in it kept.
+    // The manifest, with everything else in it kept. `displayName` is ALWAYS
+    // written — equal to the identifier, equal to the folder, whatever the
+    // person typed — because the manifest is the only source every reader
+    // has. The field is never deleted: an edit that blanks it falls back to
+    // the identifier, which is what the plugin is then called.
     const manifest: Record<string, unknown> = { ...(plugin.manifest ?? {}), name: nextName };
-    if (nextDisplay && nextDisplay !== folderName) manifest.displayName = nextDisplay;
-    else delete manifest.displayName;
+    manifest.displayName = nextDisplay || nextName;
     const manifestRel = `${this.kbDirName}/${plugin.folder}/${PLUGIN_MANIFEST_FILE}`;
     const writes: { rel: string; text: string; before: string | null }[] = [
       { rel: manifestRel, text: `${JSON.stringify(manifest, null, 2)}\n`, before: plugin.manifestText },
@@ -247,9 +257,11 @@ export class PluginRenameService {
       throw err;
     }
     this.noteChanged(wsId);
+    // Exactly what was persisted, read back through the shared rule — the
+    // response and the file can never say two different things.
     return {
       name: nextName,
-      displayName: pluginDisplayNameOf(manifest, folderName),
+      displayName: pluginDisplayNameOf(manifest),
       rewritten: writes.slice(1).map((w) => w.rel.slice(this.kbDirName.length + 1)),
     };
   }

package/src/modules/plugins/plugins.contract.ts

@@ -53,6 +53,18 @@ export interface PluginSummary {
   displayName: string;
   /** Repo-relative constituent folders, e.g. `['Plugins/GTM']`. */
   folders: string[];
+  /**
+   * Repo-relative roots the plugin LINKS — its manifest's linked-skill roots
+   * (`extensions["software.bevel.hexis"].skills`), or a bundle's
+   * `sourceSkillRoots`.
+   *
+   * Served because a plugin's page has to say which of its cards live
+   * somewhere else. A SKILL carries its own membership record (linked or
+   * inline); a TOOL carries none — a `.tool` sitting beside the skills under
+   * a linked root reaches the plugin exactly the way those skills do, and
+   * these roots are the only thing that says so.
+   */
+  linkedRoots: string[];
   /** Whether this platform writes the plugin's links — see `PluginCatalogEntry`. */
   linksAreManaged: boolean;
   /**
@@ -91,13 +103,29 @@ export interface PluginSummary {
   owners: ResolvedPrincipals;
   writers: ResolvedPrincipals;
   readers: ResolvedReaders;
+  /** The plugin's access.md says of itself that it is private — see `PluginCatalogEntry.isPrivate`. */
+  isPrivate: boolean;
+  /** What discovery left out of this plugin and why — see `PluginCatalogEntry.warnings`. */
+  warnings: string[];
   /**
-   * The caller has an OPEN join change request for this plugin (their
-   * deterministic join branch has an open CR). Always false for a member.
+   * The caller has asked to join this plugin and the ask still stands: a
+   * recorded request that is pending, one whose change request is still
+   * open, or an open join change request on their deterministic join branch.
+   * The RECORD is what makes this true the moment the subscribe call is
+   * answered — the change request may still be seconds away. False again
+   * once that change request is declined or settled: the ask is over, and
+   * the person may make it again. Always false for a member.
    */
   hasRequested: boolean;
-  /** The open join CR's number when `hasRequested` (deep-links the UI). */
+  /** The join CR's number once it exists (deep-links the UI); null before that. */
   requestNumber: number | null;
+  /**
+   * Why the last recorded request could not be sent, in the words the git
+   * work used — set only when `hasRequested` is false because the record
+   * failed, which is when the page owes the person the button back and a
+   * reason. Null in every other case, including on a server without records.
+   */
+  requestFailure?: string | null;
 }
 
 /**
@@ -108,9 +136,11 @@ export interface PluginSummary {
 export interface PluginCatalogEntry {
   /** The plugin's identity — its manifest name. */
   name: string;
-  /** What a person sees it called — the manifest's `displayName`, else the folder name. */
+  /** What a person sees it called — the manifest's `displayName`, else its `name`. */
   displayName: string;
   folders: string[];
+  /** The roots it links skills from — see `PluginSummary.linkedRoots`. */
+  linkedRoots: string[];
   /**
    * Whether this platform writes the plugin's links (a native `plugin.json`)
    * — false for a plugin read from an external format, whose links are
@@ -124,6 +154,24 @@ export interface PluginCatalogEntry {
   owners: ResolvedPrincipals;
   writers: ResolvedPrincipals;
   readers: ResolvedReaders;
+  /**
+   * The folder's access.md FRONTMATTER denies `everyone` read and names
+   * nobody but people (`isPrivateAccessMd`) — the shape a personal space is
+   * seeded with, and what a person writes to keep a plugin to a few named
+   * colleagues. The Library marks such a plugin "Private". A statement the
+   * file makes about itself, not a verdict: `readers` says who can use it.
+   */
+  isPrivate: boolean;
+  /**
+   * What discovery left out of THIS plugin and why, in plain words: an MCP
+   * server its profile selects that the registry could not keep, a skill
+   * root that is not a folder, a profile that does not exist. Attributed by
+   * folder from the discovery warnings, with the folder prefix removed, so
+   * the plugin's page can list them for the people who can fix the files —
+   * the server log is not where a plugin's owner looks. Empty when nothing
+   * was left out.
+   */
+  warnings: string[];
 }
 
 export interface IPluginIndexService {