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

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -1,4 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('mcp-oauth');
 import { and, eq, gt, isNull, lt, or } from 'drizzle-orm';
 import type { Response } from 'express';
 import type {
@@ -307,7 +310,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       .update(oauthTokens)
       .set({ lastUsedAt: now })
       .where(eq(oauthTokens.id, row.id))
-      .then(undefined, (err) => console.warn('[mcp-oauth] touch lastUsedAt failed:', err));
+      .then(undefined, (err) => log.warn('touch lastUsedAt failed:', { err }));
     return {
       token,
       clientId: row.clientId,
@@ -377,7 +380,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       );
       await this.deps.db.delete(oauthAuthCodes).where(lt(oauthAuthCodes.expiresAt, cutoff));
     } catch (err) {
-      console.warn('[mcp-oauth] token-table prune failed (non-fatal):', err instanceof Error ? err.message : err);
+      log.warn('token-table prune failed (non-fatal):', { err });
     }
     await this.deps.db.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),

package/src/modules/mcp/oauth/oauth-consent.routes.ts

@@ -1,4 +1,7 @@
 import express from 'express';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('mcp-oauth');
 import type { BevelOAuthProvider } from './bevel-oauth-provider.js';
 import { verifyAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 import '../../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
@@ -70,10 +73,7 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
     } catch (err) {
       // Message only — the raw error object can carry sensitive context
       // (redirect URIs with tokens, DB details) that must not hit stdout.
-      console.error(
-        `[mcp-oauth] complete failed for client=${st.c}:`,
-        err instanceof Error ? err.message : String(err),
-      );
+      log.error(`complete failed for client=${st.c}:`, { detail: err instanceof Error ? err.message : String(err) });
       res.status(500).json({ error: 'Internal error' });
     }
   });

package/src/modules/mcp/surface-log-throttle.ts

@@ -0,0 +1,120 @@
+/**
+ * Decides whether a request's surface-build line is worth a log entry.
+ *
+ * The stateless endpoint rebuilds the tool surface on EVERY request, and the
+ * line that reports how long that took is the measurement the design's
+ * per-request overhead is judged by — it has to keep appearing. It must not
+ * appear per request: at the measured ~100 ms a request, an active client
+ * produces thousands of identical lines a minute, and the log stops carrying
+ * the one signal it exists for (a surface that changed, or got slow).
+ *
+ * So a line is logged for a user when its SHAPE changed since the last
+ * logged line (tool or manual count — a manual that appeared, failed, or
+ * was fixed), or when a quiet interval has passed since that line, whichever
+ * comes first. In between, identical rebuilds are counted, and the next
+ * logged line carries the count so nothing is hidden, only compressed.
+ *
+ * Bounded: an entry per user, dropped once they have been quiet for the
+ * interval, so a long-running process never accumulates departed users. The
+ * pruning is one sweep per interval, not one per request — a request must
+ * not pay for every other active user — which puts the bound at TWO
+ * intervals, not one: a user who goes quiet just after a sweep is not yet
+ * quiet enough at the next one and goes at the one after. Departed users
+ * therefore cost at most the number who were active in the last two
+ * intervals, which is the price of the O(1) request.
+ */
+
+export const DEFAULT_SURFACE_LOG_INTERVAL_MS = 60_000;
+
+export interface SurfaceShape {
+  tools: number;
+  manuals: number;
+}
+
+export interface SurfaceLogDecision {
+  log: boolean;
+  /** Rebuilds with the same shape suppressed since the last logged line for this user. */
+  suppressed: number;
+}
+
+interface LastLogged {
+  /** When this user's line was last LOGGED — the interval counts from here. */
+  at: number;
+  /**
+   * When this user last rebuilt at all, logged or suppressed — what pruning
+   * counts from. A user rebuilding every second inside the interval is
+   * active, and forgetting them on a sweep would discard the suppressed count
+   * their next logged line owes.
+   */
+  seenAt: number;
+  shape: string;
+  suppressed: number;
+}
+
+export class SurfaceLogThrottle {
+  private readonly last = new Map<string, LastLogged>();
+  /** When the last sweep ran; a sweep is owed once per interval, not per request. */
+  private lastPruneAt = Number.NEGATIVE_INFINITY;
+
+  constructor(
+    private readonly intervalMs: number = DEFAULT_SURFACE_LOG_INTERVAL_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /** Record a rebuild for `userId` and say whether to log it. */
+  decide(userId: string, shape: SurfaceShape): SurfaceLogDecision {
+    const now = this.now();
+    // One sweep per interval, amortized over every request in it: a request
+    // costs O(1), not a walk of every active user, and an entry that goes
+    // quiet is gone by the second sweep after (see the class doc). The sweep
+    // skips THIS user: its entry is about to be read, and at exactly the
+    // interval it still carries the suppressed count the next line owes.
+    //
+    // `now` is the wall clock, which can step backwards (an NTP correction, a
+    // VM restored from suspend). Waiting for it to climb back past the last
+    // sweep would stall pruning for as long as the step was; a clock that
+    // went backwards instead resets the cadence, and pruning resumes in the
+    // clock's new domain on the next request.
+    const clockSteppedBack = now < this.lastPruneAt;
+    if (clockSteppedBack || now - this.lastPruneAt >= this.intervalMs) {
+      this.prune(now, userId);
+      this.lastPruneAt = now;
+    }
+    const key = `${shape.tools}/${shape.manuals}`;
+    const prev = this.last.get(userId);
+    if (prev && prev.shape === key && now - prev.at < this.intervalMs) {
+      prev.suppressed += 1;
+      prev.seenAt = now;
+      return { log: false, suppressed: prev.suppressed };
+    }
+    const suppressed = prev?.suppressed ?? 0;
+    this.last.set(userId, { at: now, seenAt: now, shape: key, suppressed: 0 });
+    return { log: true, suppressed };
+  }
+
+  /** Users currently remembered; diagnostics and tests. */
+  size(): number {
+    return this.last.size;
+  }
+
+  /**
+   * Entries for users quiet for the interval or longer carry no information;
+   * drop them. Quiet means no rebuild at all, logged or suppressed (`seenAt`):
+   * a user whose every rebuild in the interval was suppressed is not quiet,
+   * and dropping them would lose the count their next line reports. An entry
+   * stamped LATER than now was written before the clock stepped backwards:
+   * its age is unknowable across the step, so it is restamped as seen now and
+   * ages from here — otherwise a large step would keep every pre-step user
+   * for as long as the step, past the stated bound.
+   */
+  private prune(now: number, except: string): void {
+    for (const [userId, entry] of this.last) {
+      if (entry.seenAt > now) {
+        entry.seenAt = now;
+        if (entry.at > now) entry.at = now;
+      } else if (userId !== except && now - entry.seenAt >= this.intervalMs) {
+        this.last.delete(userId);
+      }
+    }
+  }
+}

package/src/modules/plugins/__tests__/bundle-dialect.e2e.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -14,6 +15,7 @@ import { PluginLinkIndex } from '../plugin-links.js';
 import { PluginLinksService } from '../plugin-links.service.js';
 import { KbPluginSource } from '../discovery/kb-plugin-source.js';
 import { MarketplaceCompilerService } from '../compile/marketplace-compiler.service.js';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 
 /**
  * A customer's repository, read as-is: lowercase `skills/` and `plugins/`
@@ -91,13 +93,14 @@ describe('bundle dialect, end to end', () => {
       JSON.stringify({ name: 'finance-kit', sourceSkillRoots: ['skills/departments/business/finance'] }),
     );
 
-    const source = new KbPluginSource();
-    access = new AccessControlService(workspaceService, KB_DIR);
-    skills = new SkillService(workspaceService, access, KB_DIR);
-    tools = new ToolManualService(workspaceService, access, KB_DIR, Date.now, source);
-    links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, Date.now, source);
-    index = new PluginIndexService(workspaceService, access, skills, tools, KB_DIR, Date.now, links, source);
-    compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, KB_DIR, { name: 'acme', owner: 'Acme' }, source);
+    const disk = new NodeFs();
+    const source = new KbPluginSource(disk);
+    access = new AccessControlService(workspaceService, KB_DIR, disk);
+    skills = new SkillService(workspaceService, access, KB_DIR, disk);
+    tools = new ToolManualService(workspaceService, access, KB_DIR, disk, source);
+    links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, source);
+    index = new PluginIndexService(workspaceService, access, skills, tools, KB_DIR, source, Date.now, links);
+    compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, KB_DIR, { name: 'acme', owner: 'Acme' }, source, disk, new NodeGitRunner());
     linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, skills, links, KB_DIR);
   });
   afterEach(async () => {

package/src/modules/plugins/__tests__/bundle-dialect.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { expandProfile, parseRegistry } from '../discovery/bundle-dialect/registry.js';
+import { readBundlePlugin } from '../discovery/bundle-dialect/bundle.source.js';
+
+/**
+ * The customer's registry and bundle, read as they mean them: a server is
+ * CALLED by its `name` (the `mcp__<name>__*` namespace skills are written
+ * against) and selected by its `id`; every field of a server the platform
+ * does not know rides along; a server the registry could not keep is named
+ * with the reason wherever a profile asks for it; and what a bundle says
+ * about itself beyond name, version and description survives to the
+ * compiled plugin. Driven through the two public readers, on crafted input.
+ */
+
+const registryText = (extra: Record<string, unknown> = {}) =>
+  JSON.stringify({
+    version: 1,
+    servers: [
+      { id: 'ado', name: 'ado', config: { command: 'npx', args: ['-y', '@azure-devops/mcp', 'acme'], startup_timeout_sec: 120 } },
+      { id: 'figma-stdio', name: 'figma', config: { command: 'npx', args: ['-y', 'figma-mcp'] } },
+      { id: 'figma-remote', name: 'figma', config: { type: 'http', url: 'https://mcp.figma.com/mcp' } },
+      { id: 'docs', name: 'acme-docs', config: { command: 'node', args: ['server.js', { $fromFile: 'x.json' }] } },
+    ],
+    profiles: [
+      { id: 'global', servers: ['ado', 'figma-stdio', 'docs'] },
+      { id: 'remote', extends: 'global', servers: ['figma-remote'] },
+    ],
+    ...extra,
+  });
+
+describe('registry: servers are called by name, selected by id', () => {
+  it('keys an expanded profile by the running name, with the id as the name when none is given', () => {
+    const registry = parseRegistry(
+      JSON.stringify({
+        servers: [
+          { id: 'figma-stdio', name: 'figma', config: { command: 'npx', args: ['-y', 'figma-mcp'] } },
+          { id: 'jira', config: { command: 'npx', args: ['-y', 'jira-mcp'] } },
+        ],
+        profiles: [{ id: 'global', servers: ['figma-stdio', 'jira'] }],
+      }),
+    );
+    const { mcpServers, warnings } = expandProfile(registry, 'global');
+    expect(Object.keys(mcpServers).sort()).toEqual(['figma', 'jira']);
+    expect(warnings).toEqual([]);
+  });
+
+  it('carries every field it does not read — the customer\'s startup_timeout_sec survives', () => {
+    const registry = parseRegistry(registryText());
+    const { mcpServers } = expandProfile(registry, 'global');
+    expect(mcpServers.ado).toEqual({
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', '@azure-devops/mcp', 'acme'],
+      startup_timeout_sec: 120,
+    });
+  });
+
+  it('two transports of one server: a profile picks one, and picking both is a reported conflict the nearer profile wins', () => {
+    const registry = parseRegistry(registryText());
+    // `remote` extends `global`: its own figma-remote is nearer than global's figma-stdio.
+    const remote = expandProfile(registry, 'remote');
+    expect(remote.mcpServers.figma).toMatchObject({ type: 'streamable-http', url: 'https://mcp.figma.com/mcp' });
+    expect(remote.warnings).toContainEqual(
+      expect.stringContaining('selects both "figma-remote" and "figma-stdio", which are both named "figma" — "figma-stdio" left out'),
+    );
+    const global = expandProfile(registry, 'global');
+    expect(global.mcpServers.figma).toMatchObject({ type: 'stdio', command: 'npx' });
+  });
+
+  it('names a selected server the registry could not keep, with the reason, where the profile asks for it', () => {
+    const registry = parseRegistry(registryText());
+    expect(registry.rejected.get('docs')).toBe('args must be a list of strings');
+    const { mcpServers, warnings } = expandProfile(registry, 'global');
+    expect(mcpServers['acme-docs']).toBeUndefined();
+    expect(warnings).toContainEqual(
+      'registry.json: profile "global" selects server "docs", which was left out — args must be a list of strings',
+    );
+  });
+
+  it('a name a client cannot key on does not lose the server: it runs under its id, and the author is told', () => {
+    const registry = parseRegistry(
+      JSON.stringify({
+        servers: [{ id: 'ok-id', name: 'Not A Name', config: { command: 'x' } }],
+        profiles: [{ id: 'p', servers: ['ok-id'] }],
+      }),
+    );
+    expect(registry.warnings).toEqual([
+      'registry.json: server "ok-id" is named "Not A Name", which cannot be a server name (lowercase alphanumeric with `_`/`-`) — it runs as "ok-id"',
+    ]);
+    expect(Object.keys(expandProfile(registry, 'p').mcpServers)).toEqual(['ok-id']);
+  });
+
+  it('a name that is present but blank, or not a string, is said too — the server runs under its id', () => {
+    const registry = parseRegistry(
+      JSON.stringify({
+        servers: [
+          { id: 'a', name: '   ', config: { command: 'x' } },
+          { id: 'b', name: 42, config: { command: 'x' } },
+          { id: 'c', name: 'c', config: { command: 'x' } },
+        ],
+      }),
+    );
+    expect(registry.warnings).toEqual([
+      'registry.json: server "a" has a name that is blank or not a string — it runs as "a"',
+      'registry.json: server "b" has a name that is blank or not a string — it runs as "b"',
+    ]);
+    expect([...registry.servers.values()].map((s) => s.name)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('carries a field spelled __proto__ as a field, not as a prototype', () => {
+    // Raw text on purpose: in a JavaScript literal `__proto__` sets the
+    // prototype and never reaches JSON; from a file it is an ordinary key.
+    const registry = parseRegistry('{"servers":[{"id":"odd","config":{"command":"x","__proto__":{"polluted":true}}}]}');
+    const entry = registry.servers.get('odd')!.entry as Record<string, unknown>;
+    expect(Object.prototype.hasOwnProperty.call(entry, '__proto__')).toBe(true);
+    expect((entry as { polluted?: unknown }).polluted).toBeUndefined();
+  });
+
+  it('a rejected server carries the reason the entry failed, not its name', () => {
+    const registry = parseRegistry(
+      JSON.stringify({ servers: [{ id: 'docs', name: 'acme-docs', config: { command: 'node', args: [{ x: 1 }] } }] }),
+    );
+    expect(registry.rejected.get('docs')).toBe('args must be a list of strings');
+  });
+});
+
+describe('bundle: what it says about itself survives', () => {
+  it('carries author, keywords and the interface block into the manifest, beside name, version and description', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-bundle-'));
+    try {
+      const dir = path.join(root, 'plugins', 'ado');
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(
+        path.join(dir, 'plugin.bundle.json'),
+        JSON.stringify({
+          name: 'ado',
+          version: '1.3.5',
+          description: 'Azure DevOps skills.',
+          author: { name: 'acme' },
+          keywords: ['ado', 'mcp'],
+          interface: { displayName: 'Azure DevOps', category: 'Productivity', brandColor: '#2563EB', defaultPrompt: ['Show my work.'] },
+          sourceSkillRoots: ['skills/ado'],
+        }),
+      );
+      const warnings: string[] = [];
+      const plugin = await readBundlePlugin(dir, 'plugins/ado', 'ado', null, warnings, []);
+      expect(plugin?.manifest).toEqual({
+        name: 'ado',
+        version: '1.3.5',
+        description: 'Azure DevOps skills.',
+        displayName: 'Azure DevOps',
+        author: { name: 'acme' },
+        keywords: ['ado', 'mcp'],
+        interface: { displayName: 'Azure DevOps', category: 'Productivity', brandColor: '#2563EB', defaultPrompt: ['Show my work.'] },
+      });
+      expect(plugin?.displayName).toBe('Azure DevOps');
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/modules/plugins/__tests__/compile-marketplace.test.ts

@@ -1,4 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -10,6 +12,10 @@ import { SkillService } from '../../skills/skills.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { PluginLinkIndex } from '../plugin-links.js';
 import { MarketplaceCompilerService } from '../compile/marketplace-compiler.service.js';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import express from 'express';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { registerSkillsTools } from '../../skills/skills.tools.js';
 
 /**
  * Source in, distribution out — for one caller. The real resolver decides
@@ -24,6 +30,7 @@ describe('compileMarketplace', () => {
   let root: string;
   let repo: string;
   let compiler: MarketplaceCompilerService;
+  let catalog: SkillService;
 
   const write = async (rel: string, text: string) => {
     const abs = path.join(repo, rel);
@@ -52,6 +59,10 @@ describe('compileMarketplace', () => {
       'Plugins/GTM/plugin.json',
       JSON.stringify({
         name: 'gtm',
+        // Both names, as every manifest this platform writes carries them —
+        // and spelled differently from the folder `Plugins/GTM`, so a compiler
+        // that fell back to the folder for either would fail here.
+        displayName: 'Go To Market',
         version: '2.1.0',
         description: 'Go to market',
         extensions: { 'software.bevel.hexis': { skills: ['Skills/Eng/deploy'] } },
@@ -78,14 +89,27 @@ describe('compileMarketplace', () => {
     await write('Skills/Sales/access.md', '---\n---\nread:\n  - everyone\n');
     await write('Skills/Sales/pitch/SKILL.md', '---\ndescription: Pitch.\n---\n');
 
-    const access = new AccessControlService(workspaceService, KB_DIR);
-    const skills = new SkillService(workspaceService, access, KB_DIR);
-    const links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR);
-    compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, KB_DIR, {
-      name: 'acme-hexis',
-      owner: 'Acme',
-      knowledgeBaseMcp: { name: 'hexis', url: 'https://kb.acme.com/api/mcp' },
-    });
+    const disk = new NodeFs();
+    const source = new KbPluginSource(disk);
+    const access = new AccessControlService(workspaceService, KB_DIR, disk);
+    const skills = new SkillService(workspaceService, access, KB_DIR, disk);
+    catalog = skills;
+    const links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, source);
+    compiler = new MarketplaceCompilerService(
+      workspaceService,
+      access,
+      skills,
+      links,
+      KB_DIR,
+      {
+        name: 'acme-hexis',
+        owner: 'Acme',
+        knowledgeBaseMcp: { name: 'hexis', url: 'https://kb.acme.com/api/mcp' },
+      },
+      source,
+      disk,
+      new NodeGitRunner(),
+    );
   });
   afterEach(() => fs.rm(root, { recursive: true, force: true }));
 
@@ -127,8 +151,19 @@ describe('compileMarketplace', () => {
     expect(paths).toContain('skills/pitch/SKILL.md');
     expect(paths).toContain('skills/outreach/SKILL.md');
 
-    // The bundle depends on every other plugin; the catalogues list them all.
-    expect(json(tree, 'plugins/hexis-all/.claude-plugin/plugin.json').dependencies.sort()).toEqual(['gtm', 'skills-and-knowledge']);
+    // The bundle IS everything the caller may read — every skill once and the
+    // knowledge base's MCP endpoint — with no dependency list: only Claude
+    // Code resolves one, and Cowork and claude.ai install content alone.
+    const bundleManifest = json(tree, 'plugins/hexis-all/.claude-plugin/plugin.json');
+    expect(bundleManifest).not.toHaveProperty('dependencies');
+    expect(bundleManifest.version).toMatch(/^0\.0\.0-/);
+    for (const name of ['deploy', 'pitch', 'outreach']) expect(paths).toContain(`plugins/hexis-all/skills/${name}/SKILL.md`);
+    expect(paths).toContain('plugins/hexis-all/skills/deploy/references/notes.md');
+    expect(json(tree, 'plugins/hexis-all/.mcp.json')).toEqual({
+      mcpServers: { hexis: { type: 'streamable-http', url: 'https://kb.acme.com/api/mcp' } },
+    });
+    // Claude's catalogue lists it; Codex's does not, since Codex installs
+    // every entry on add and the bundle repeats what the others carry.
     const claude = json(tree, '.claude-plugin/marketplace.json');
     expect(claude.name).toBe('acme-hexis');
     expect(claude.plugins.map((p: { name: string; source: string }) => [p.name, p.source])).toEqual([
@@ -137,12 +172,43 @@ describe('compileMarketplace', () => {
       ['hexis-all', './plugins/hexis-all'],
     ]);
     const codex = json(tree, '.agents/plugins/marketplace.json');
+    expect(codex.plugins.map((p: { name: string }) => p.name)).toEqual(['gtm', 'skills-and-knowledge']);
     expect(codex.plugins.every((p: { policy: { installation: string } }) => p.policy.installation === 'INSTALLED_BY_DEFAULT')).toBe(true);
     expect(codex.plugins[0].source).toEqual({ source: 'local', path: './plugins/gtm' });
     expect(text(tree, 'README.md')).toContain('Compiled from Acme');
     expect(tree.warnings).toEqual([]);
   });
 
+  it('ships a skill whose frontmatter carries a lifecycle, and lists it over MCP like any other', async () => {
+    // `metadata.lifecycle` is not a field this platform reads any more. A
+    // SKILL.md that still carries one is an ordinary readable skill: it
+    // compiles into every layout and the agent surfaces name it.
+    await write(
+      'Skills/Sales/legacy-pitch/SKILL.md',
+      '---\ndescription: The old pitch.\nmetadata:\n  lifecycle: retired\n  owner: "Sales"\n---\nBody\n',
+    );
+
+    const tree = await compiler.compileFor({ userEmail: 'sam@x.io' });
+    const paths = [...tree.files.keys()];
+    expect(paths).toContain('plugins/skills-and-knowledge/skills/legacy-pitch/SKILL.md');
+    expect(paths).toContain('plugins/hexis-all/skills/legacy-pitch/SKILL.md');
+    expect(paths).toContain('skills/legacy-pitch/SKILL.md');
+    expect(tree.warnings).toEqual([]);
+
+    // The MCP surface: `list_skills` answers with the catalog verbatim, and
+    // the tool's own description names what is available.
+    const listed = await catalog.listSkills('sam@x.io');
+    expect(listed.map((x) => x.name)).toContain('legacy-pitch');
+    expect(listed.find((x) => x.name === 'legacy-pitch')).not.toHaveProperty('lifecycle');
+
+    const registry = new ToolRegistry();
+    // The routes are registered but never called here: only the DEFINITION,
+    // which names the catalog, is under test.
+    registerSkillsTools(registry, express.Router(), () => undefined, () => () => undefined, catalog);
+    const listSkills = (await registry.listExternal({ userEmail: 'sam@x.io' })).find((t) => t.name === 'list_skills');
+    expect(listSkills?.description).toContain('`legacy-pitch`');
+  });
+
   it('ships only mcp servers a client could run, and names each one it leaves out', async () => {
     // Written as text, not from an object literal: a literal `__proto__` key
     // sets the prototype instead of an own property, and the point is a
@@ -291,4 +357,67 @@ describe('compileMarketplace', () => {
     const tree = await compiler.compileFor({ userEmail: 'sam@x.io' });
     expect(text(tree, 'plugins/gtm/skills/deploy/SKILL.md')).toContain('Ship it.');
   });
+
+  it("ships the plugin folder's own files beside the skills — not the platform's, not the tools, not a second copy of the skills", async () => {
+    await write('Plugins/GTM/CONVENTIONS.md', '# How we do GTM\n');
+    await write('Plugins/GTM/docs/playbook.md', 'playbook');
+    await write('Plugins/GTM/.bevelignore', 'x');
+    const tree = await compiler.compileFor({ userEmail: 'sam@x.io' });
+    const paths = [...tree.files.keys()];
+    expect(text(tree, 'plugins/gtm/CONVENTIONS.md')).toBe('# How we do GTM\n');
+    expect(text(tree, 'plugins/gtm/docs/playbook.md')).toBe('playbook');
+    // The skills folder is copied by NAME once, never as a second tree.
+    expect(paths.filter((p) => p.startsWith('plugins/gtm/skills/outreach/SKILL.md'))).toHaveLength(1);
+    expect(paths.some((p) => p.endsWith('.bevelignore') || p.endsWith('access.md') || p.includes('software.bevel.hexis'))).toBe(false);
+    // The manifests are the compiler's, not the checked-in source's.
+    expect(json(tree, 'plugins/gtm/plugin.json').extensions).toBeUndefined();
+  });
+
+  it('carries what the source manifest says about itself, and every server field it does not judge', async () => {
+    await write(
+      'Plugins/GTM/plugin.json',
+      JSON.stringify({
+        name: 'gtm',
+        version: '2.1.0',
+        description: 'Go to market',
+        author: { name: 'Acme' },
+        keywords: ['sales', 'crm'],
+        interface: { displayName: 'Go To Market', category: 'Sales', brandColor: '#123456' },
+      }),
+    );
+    await write(
+      'Plugins/GTM/mcp.json',
+      JSON.stringify({
+        mcpServers: {
+          local: { type: 'stdio', command: 'npx', args: ['-y', 'x'], startup_timeout_sec: 120 },
+          remote: { type: 'streamable-http', url: 'https://mcp.example', timeout_ms: 5000, note: 'uses ${SECRET}' },
+        },
+      }),
+    );
+    const tree = await compiler.compileFor({ userEmail: 'sam@x.io' });
+    expect(json(tree, 'plugins/gtm/plugin.json')).toMatchObject({ author: { name: 'Acme' }, keywords: ['sales', 'crm'] });
+    expect(json(tree, 'plugins/gtm/.claude-plugin/plugin.json')).toMatchObject({ author: { name: 'Acme' }, keywords: ['sales', 'crm'] });
+    expect(json(tree, 'plugins/gtm/.codex-plugin/plugin.json')).toMatchObject({
+      author: { name: 'Acme' },
+      interface: { displayName: 'Go To Market', category: 'Sales', brandColor: '#123456' },
+    });
+    const mcp = json(tree, 'plugins/gtm/.mcp.json');
+    expect(mcp.mcpServers.local).toEqual({ type: 'stdio', command: 'npx', args: ['-y', 'x'], startup_timeout_sec: 120 });
+    // A field holding a vault reference is not a client's to see.
+    expect(mcp.mcpServers.remote).toEqual({ type: 'streamable-http', url: 'https://mcp.example', timeout_ms: 5000 });
+  });
+
+  it('a plugin with no presentation block of its own still tells Codex what it is called', async () => {
+    const tree = await compiler.compileFor({ userEmail: 'sam@x.io' });
+    expect(json(tree, 'plugins/gtm/.codex-plugin/plugin.json').interface).toEqual({ displayName: 'Go To Market' });
+  });
+
+  it('a partial presentation block keeps what it says and gains the name it does not', async () => {
+    await write(
+      'Plugins/GTM/plugin.json',
+      JSON.stringify({ name: 'gtm', displayName: 'Go To Market', version: '2.1.0', description: 'Go to market', interface: { category: 'Sales' } }),
+    );
+    const tree = await compiler.compileFor({ userEmail: 'sam@x.io' });
+    expect(json(tree, 'plugins/gtm/.codex-plugin/plugin.json').interface).toEqual({ category: 'Sales', displayName: 'Go To Market' });
+  });
 });