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

package/src/modules/workspace/__tests__/workspace.routes.read-gate.test.ts

@@ -182,11 +182,10 @@ describe('read-permission gates on human read routes', () => {
 
   it('keeps the structural root folders visible even when nothing is readable', async () => {
     // A user with no read grants: the access batch denies everything. The
-    // structural top-level folders (KnowledgeBase, Data, Agents, Pipelines,
-    // Plugins) must still resolve readable (so the explorer renders its
-    // section view), while their contents stay gated. The retired Skills/
-    // and Tools/ roots get NO structural treatment — they are ordinary
-    // (denied) folders now.
+    // structural top-level folders (KnowledgeBase, Skills, Data, Agents,
+    // Pipelines, Plugins) must still resolve readable (so the explorer renders
+    // its section view), while their contents stay gated. The retired Tools/
+    // root gets NO structural treatment — it is an ordinary (denied) folder.
     h = await makeHarness({ allowFn: () => false });
     expect((await get('/files')).status).toBe(200);
     const filter = h.listFilesFilter();
@@ -208,8 +207,8 @@ describe('read-permission gates on human read routes', () => {
     expect(verdict.get(`${KB}/Agents`)).toBe(true);
     expect(verdict.get(`${KB}/Pipelines`)).toBe(true);
     expect(verdict.get(`${KB}/Plugins`)).toBe(true);
-    // Retired roots: no override, the deny-all batch verdict stands.
-    expect(verdict.get(`${KB}/Skills`)).toBe(false);
+    expect(verdict.get(`${KB}/Skills`)).toBe(true);
+    // Retired root: no override, the deny-all batch verdict stands.
     expect(verdict.get(`${KB}/Tools`)).toBe(false);
     // Their contents: still gated (the override matches only the exact folder).
     expect(verdict.get(`${KB}/KnowledgeBase/Open/a.md`)).toBe(false);

package/src/modules/workspace/__tests__/workspace.service.list-cloned.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { WorkspaceService } from '../workspace.service.js';
+
+/**
+ * `listClonedWorkspaces` is what the remote sync enumerates. It must read the
+ * DISK, not the in-memory bootstrap cache: clones survive a restart, and a
+ * hook that fires before anyone has opened a branch must still find them.
+ */
+describe('WorkspaceService.listClonedWorkspaces', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-ws-list-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function clone(dirName: string, withGit = true) {
+    const repo = path.join(root, dirName, 'knowledge-base');
+    await fs.mkdir(withGit ? path.join(repo, '.git') : repo, { recursive: true });
+  }
+
+  it('finds every finished clone on disk without any branch having been opened this process', async () => {
+    await clone('main');
+    await clone('ali%2Fnew-skill');
+    // Half-built: the directory exists but the clone never finished.
+    await clone('juan%2Fabandoned', false);
+    // Not one of ours: the name is not the encoding of any branch.
+    await clone('weird%zz');
+    // A stray file at the root is ignored.
+    await fs.writeFile(path.join(root, 'notes.txt'), 'x');
+
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base');
+    const found = await svc.listClonedWorkspaces();
+    expect(found.sort((a, b) => a.branch.localeCompare(b.branch))).toEqual([
+      { id: 'ali%2Fnew-skill', branch: 'ali/new-skill' },
+      { id: 'main', branch: 'main' },
+    ]);
+  });
+
+  it('is empty when the workspaces root does not exist yet', async () => {
+    const svc = new WorkspaceService(path.join(root, 'missing'), 'https://example.test/kb.git', 'knowledge-base');
+    expect(await svc.listClonedWorkspaces()).toEqual([]);
+  });
+});
+
+describe('WorkspaceService.listClonedWorkspaces — what is not a clone', () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-ws-list-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('a directory whose name round-trips but is not a branch git accepts', async () => {
+    // `foo!`, `-leading-dash` and `a..b` survive encodeURIComponent unchanged, so
+    // only the validator can exclude them; `has space` does not round-trip and
+    // is excluded one step earlier. Both guards have to hold.
+    for (const name of ['main', 'foo!', '-leading-dash', 'a..b', 'has space']) {
+      await fs.mkdir(path.join(root, name, 'knowledge-base', '.git'), { recursive: true });
+    }
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base');
+    expect(await svc.listClonedWorkspaces()).toEqual([{ id: 'main', branch: 'main' }]);
+  });
+
+  it('a branch whose bootstrap is in flight right now', async () => {
+    await fs.mkdir(path.join(root, 'main', 'knowledge-base', '.git'), { recursive: true });
+    await fs.mkdir(path.join(root, 'ali%2Fx', 'knowledge-base', '.git'), { recursive: true });
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base');
+    // While a clone runs, `.git` exists but the tree is not checked out yet.
+    // The listing asks the public predicate, which is stubbed here rather than
+    // the tracker behind it — no public seam can hold a real clone open.
+    vi.spyOn(svc, 'isBootstrapInFlight').mockImplementation((branch) => branch === 'ali/x');
+    expect(await svc.listClonedWorkspaces()).toEqual([{ id: 'main', branch: 'main' }]);
+  });
+
+  it('a root that is a file counts as no root, not as a clone list', async () => {
+    // A FILE where the root should be: readdir fails with ENOTDIR on POSIX and
+    // ENOENT on Windows — both "no root", so an empty list. A permission
+    // failure is the case that must propagate, and there is no portable way
+    // to stage one in a temp dir; the code path is the same `throw err`.
+    const file = path.join(root, 'not-a-dir');
+    await fs.writeFile(file, 'x');
+    const svc = new WorkspaceService(file, 'https://example.test/kb.git', 'knowledge-base');
+    expect(await svc.listClonedWorkspaces()).toEqual([]);
+  });
+});

package/src/modules/workspace/__tests__/workspace.service.missing-branch.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { isMissingRemoteBranchFailure } from '../../../shared/domain-errors.js';
+
+/**
+ * The one line that decides whether a failed bootstrap is "this branch does
+ * not exist" (410, the browser says so) or "something is wrong" (500). Git's
+ * two wordings for a missing ref are matched; an unreachable host or a
+ * refused credential must NOT be, or a deployment outage would read as
+ * "your branch is gone".
+ */
+describe('isMissingRemoteBranchFailure', () => {
+  it('recognises both of git’s wordings for a ref origin does not have', () => {
+    expect(
+      isMissingRemoteBranchFailure(
+        "Command failed: git clone -b sync-test/conflict-2 https://[REDACTED]@github.com/x/y.git /w\nfatal: Remote branch sync-test/conflict-2 not found in upstream origin",
+      ),
+    ).toBe(true);
+    expect(isMissingRemoteBranchFailure("fatal: couldn't find remote ref refs/heads/ali/x")).toBe(true);
+  });
+
+  it('does not mistake an unreachable host or a refused credential for a missing branch', () => {
+    expect(
+      isMissingRemoteBranchFailure("fatal: unable to access 'https://github.com/x/y.git/': Could not resolve host: github.com"),
+    ).toBe(false);
+    expect(isMissingRemoteBranchFailure('remote: Invalid username or password.\nfatal: Authentication failed')).toBe(false);
+    expect(isMissingRemoteBranchFailure('fatal: repository not found')).toBe(false);
+  });
+});

package/src/modules/workspace/__tests__/workspace.service.read-filter.test.ts

@@ -38,8 +38,14 @@ describe('WorkspaceService.listFiles — read filter', () => {
     await mkFile(workspaceDir, 'Open/a.md');
     await mkFile(workspaceDir, 'Open/b.md');
     await mkFile(workspaceDir, 'Secret/s1.md');
+    await mkFile(workspaceDir, 'Secret/Vault/v1.md');
     await mkFile(workspaceDir, 'Mixed/hidden.md');
     await mkFile(workspaceDir, 'top.md');
+    // A denied folder with a grant below it: Scopes/ itself is closed, but
+    // Scopes/Deploy/ is shared (a linked skill's folder opened to a plugin's
+    // readers, say), and its files are readable.
+    await mkFile(workspaceDir, 'Scopes/Deploy/SKILL.md');
+    await mkFile(workspaceDir, 'Scopes/other.md');
     svc = new WorkspaceService(root, 'https://example.invalid/repo.git', KB);
     await svc.getWorkspacePath(workspaceId);
   });
@@ -64,27 +70,51 @@ describe('WorkspaceService.listFiles — read filter', () => {
     expect(filtered).toEqual(unfiltered);
   });
 
-  it('drops denied files and denied directories (subtree skipped)', async () => {
-    const asked: string[] = [];
-    const filter: ReadTreeFilter = async (ps) => {
-      asked.push(...ps);
-      return new Map(ps.map((p) => [p, !(p.includes('Secret') || p.endsWith('hidden.md'))]));
-    };
-    const tree = await svc.listFiles(workspaceId, filter);
-    const all = paths(tree);
+  it('drops denied files, and a denied directory with nothing readable beneath it', async () => {
+    const filter: ReadTreeFilter = async (ps) =>
+      new Map(ps.map((p) => [p, !(p.includes('Secret') || p.includes('Scopes') || p.endsWith('hidden.md'))]));
+    const all = paths(await svc.listFiles(workspaceId, filter));
 
     // Readable files survive.
     expect(all).toContain('Open/a.md');
     expect(all).toContain('Open/b.md');
     expect(all).toContain('top.md');
-    // Denied directory and its whole subtree are gone.
+    // A denied directory whose whole subtree is denied is gone, with the
+    // subtree — including a nested folder the walk did look into.
     expect(all).not.toContain('Secret');
     expect(all).not.toContain('Secret/s1.md');
+    expect(all).not.toContain('Secret/Vault');
+    expect(all).not.toContain('Scopes');
     // Denied file is gone.
     expect(all).not.toContain('Mixed/hidden.md');
-    // The denied directory's subtree is never walked — the filter is never
-    // asked about a path inside Secret/.
-    expect(asked.some((p) => p.startsWith('Secret/'))).toBe(false);
+  });
+
+  it('keeps a denied directory as the way to what is readable beneath it', async () => {
+    // Scopes/ is closed; Scopes/Deploy/ and its file are shared. The closed
+    // folder shows as a container — the reader can reach the skill through
+    // the tree — with its own contents still filtered (other.md is gone).
+    const filter: ReadTreeFilter = async (ps) =>
+      new Map(ps.map((p) => [p, p.startsWith('Scopes/Deploy') || (!p.includes('Secret') && !p.includes('Scopes') && !p.endsWith('hidden.md'))]));
+    const all = paths(await svc.listFiles(workspaceId, filter));
+    expect(all).toContain('Scopes');
+    expect(all).toContain('Scopes/Deploy');
+    expect(all).toContain('Scopes/Deploy/SKILL.md');
+    expect(all).not.toContain('Scopes/other.md');
+    // Unchanged for a subtree with nothing readable in it.
+    expect(all).not.toContain('Secret');
+  });
+
+  it('keeps a closed folder whose only readable content is an EMPTY sub-folder', async () => {
+    // A readable folder is kept on its own verdict, children or not — so the
+    // closed folder above it has a child, and stays as the way there.
+    await fs.mkdir(path.join(workspaceDir, 'Scopes', 'Empty'), { recursive: true });
+    const filter: ReadTreeFilter = async (ps) =>
+      new Map(ps.map((p) => [p, p === 'Scopes/Empty' || (!p.includes('Secret') && !p.includes('Scopes') && !p.endsWith('hidden.md'))]));
+    const all = paths(await svc.listFiles(workspaceId, filter));
+    expect(all).toContain('Scopes');
+    expect(all).toContain('Scopes/Empty');
+    expect(all).not.toContain('Scopes/Deploy');
+    expect(all).not.toContain('Scopes/other.md');
   });
 
   it('keeps a readable directory left empty after filtering (D4)', async () => {

package/src/modules/workspace/startup/steps/__tests__/steps.test.ts

@@ -7,11 +7,13 @@ import path from 'node:path';
 import { KbStartupRunner } from '../../kb-startup-runner.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../../on-server-start.js';
 import { GroupsToPluginsStep } from '../groups-to-plugins.step.js';
+import { PluginManifestsStep } from '../plugin-manifests.step.js';
 import { RolesYamlStep } from '../roles-yaml.step.js';
 import { renderRolesYaml } from '../../../../access-model/render-roles-yaml.js';
 import { TemplateFilesStep } from '../template-files.step.js';
 import { buildSeedTree } from '../seed-tree.js';
 import { defaultKbTemplateDir } from '../../../../../assets.js';
+import { DEFAULT_KB_LAYOUT, configureKbLayout, renderKbLayoutPlaceholders } from '@bevel-software/platform-shared';
 
 const execFileAsync = promisify(execFile);
 
@@ -54,6 +56,7 @@ beforeEach(async () => {
 
 afterEach(async () => {
   vi.restoreAllMocks();
+  configureKbLayout({ ...DEFAULT_KB_LAYOUT });
   await fs.rm(root, { recursive: true, force: true });
 });
 
@@ -109,8 +112,9 @@ async function exists(dir: string, rel: string): Promise<boolean> {
 
 const norm = (text: string) => text.replace(/\r\n?/g, '\n');
 
+/** The template as the step writes it under the default layout — placeholders rendered. */
 async function template(name: string): Promise<string> {
-  return fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8');
+  return renderKbLayoutPlaceholders(await fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8'), DEFAULT_KB_LAYOUT);
 }
 
 /** Every required file + reserved root already present, from the real template. */
@@ -122,6 +126,7 @@ async function fullScaffold(): Promise<Record<string, string>> {
     '.gitignore': await template('gitignore.template'),
     'KnowledgeBase/.gitkeep': '',
     'Plugins/.gitkeep': '',
+    'Skills/.gitkeep': '',
   };
 }
 
@@ -144,12 +149,39 @@ describe('TemplateFilesStep', () => {
       // Reserved roots materialize as <dir>/.gitkeep.
       expect(await exists(dir, 'KnowledgeBase/.gitkeep')).toBe(true);
       expect(await exists(dir, 'Plugins/.gitkeep')).toBe(true);
+      expect(await exists(dir, 'Skills/.gitkeep')).toBe(true);
       const subject = (await git(dir, ['log', '--format=%s', '-1'])).trim();
       expect(subject).toMatch(/^Add missing KB scaffolding: /);
       expect(subject).toContain('.gitignore');
     }
   });
 
+  it('renders the managed files with the deployment\'s own root names', async () => {
+    // A deployment that renamed its roots must hand the agent a guide naming
+    // the folders it will find, and an ignore file hiding the real ones.
+    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    await seedUpstream({ 'marker.txt': 'seeded' });
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    const agents = norm(await fs.readFile(path.join(dir, 'AGENTS.md'), 'utf8'));
+    expect(agents).toContain('plugins/<Plugin>/plugin.json');
+    expect(agents).toContain('`docs/`');
+    expect(agents).not.toContain('{{');
+    expect(agents).not.toContain('KnowledgeBase/');
+    const ignore = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8')).split('\n').map((l) => l.trim());
+    expect(ignore).toContain('plugins/');
+    // The skills root stays VISIBLE: the Skills & Tools sidebar reads it from the workspace tree.
+    expect(ignore).not.toContain('skills/');
+    expect(ignore).not.toContain('Plugins/');
+    expect(await exists(dir, 'docs/.gitkeep')).toBe(true);
+
+    // And a second boot sees the rendered guide as current: no churn commit.
+    await makeRunner([new TemplateFilesStep()]).runAll();
+    const again = await checkout(DEFAULT_BRANCH);
+    expect((await git(again, ['rev-list', '--count', 'HEAD'])).trim()).toBe('2'); // init + scaffolding
+  });
+
   it('replaces a drifted AGENTS.md, and says so when that is the only change', async () => {
     await seedUpstream({ ...(await fullScaffold()), 'AGENTS.md': 'stale conventions\n' });
     await makeRunner([new TemplateFilesStep()]).runAll();
@@ -184,20 +216,160 @@ describe('TemplateFilesStep', () => {
     const lines = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8')).split('\n').map((l) => l.trim());
     expect(lines).toContain('MyStuff/'); // the operator's rules survive
     expect(lines).toContain('AGENTS.md'); // the platform's rule was appended
+    expect(lines).not.toContain('Skills/'); // never the skills root — the Library's tree needs it
+  });
+
+  it('drops the Skills/ rule an earlier release appended, and its comment, keeping every other rule', async () => {
+    // A knowledge base whose ignore file was topped up by the release that
+    // hid the skills root: the platform's comment + line sit at the end. The
+    // Skills & Tools sidebar reads that root from the workspace tree now, so
+    // the rule comes out exactly as it went in — nothing of the operator's moves.
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] =
+      '# mine\n.git/\nAGENTS.md\nPlugins/\n\n# Added by the platform: the conventions doc is not node content.\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    const text = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'));
+    expect(text).toBe('# mine\n.git/\nAGENTS.md\nPlugins/\n');
+    // Idempotent: a second boot has nothing to change.
+    await makeRunner([new TemplateFilesStep()]).runAll();
+    const again = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(again, '.bevelignore'), 'utf8'))).toBe(text);
+  });
+
+  it("drops the template's own Skills/ rule from a KB seeded by that release, comment included — whatever root the comment named", async () => {
+    // The previous template listed the rule under its own explanatory line,
+    // ending with the plugins root's name of the day; a deployment may have
+    // renamed that root since, so the line is known by its opening.
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] =
+      'AGENTS.md\nPlugins/\n# The shared-skills root is rendered by the Skills & Tools app, like Groups/.\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe('AGENTS.md\nPlugins/\n');
+  });
+
+  it('recognises the legacy comment for a renamed plugins root with a space in its name', async () => {
+    // The name between the fixed opening and closing is judged by the one
+    // root-name rule the platform has, so every name it could have rendered
+    // there is recognised — and nothing a root cannot be called is.
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] =
+      'AGENTS.md\nPlugins/\n# The shared-skills root is rendered by the Skills & Tools app, like My Plugins/.\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe('AGENTS.md\nPlugins/\n');
+  });
+
+  it("keeps an operator's Skills/ rule whose own comment merely opens like the platform's", async () => {
+    // Provenance is the platform's EXACT comment. A comment that begins the
+    // same way and goes on differently was never written by the platform.
+    const scaffold = await fullScaffold();
+    const text =
+      'AGENTS.md\nPlugins/\n# The shared-skills root is rendered by the Skills & Tools app, and I hide it anyway\nSkills/\n';
+    scaffold['.bevelignore'] = text;
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe(text);
+  });
+
+  it("keeps a Skills/ rule the operator wrote themselves — provenance is the platform's comment", async () => {
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] = 'AGENTS.md\nPlugins/\n# I hide skills on purpose\nSkills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe(
+      'AGENTS.md\nPlugins/\n# I hide skills on purpose\nSkills/\n',
+    );
+  });
+
+  it('seeds a binary template file byte for byte and keeps a script executable — text is what decodes', async () => {
+    const customTemplate = path.join(root, 'custom-template-bytes');
+    // The packaged template as a base, plus two files it does not ship.
+    await fs.cp(TEMPLATE_DIR, customTemplate, { recursive: true });
+    await fs.mkdir(path.join(customTemplate, 'assets'), { recursive: true });
+    await fs.mkdir(path.join(customTemplate, 'scripts'), { recursive: true });
+    // Not UTF-8, and holding a NUL: text by no reading of the bytes. A
+    // name-based rule once sent this through the decoder and changed it.
+    const binary = Buffer.from([0x89, 0x50, 0x00, 0xff, 0xfe, 0x7b, 0x7b, 0x7d, 0x7d]);
+    await fs.writeFile(path.join(customTemplate, 'assets', '.logo.bin'), binary);
+    await fs.writeFile(path.join(customTemplate, 'scripts', 'run.sh'), '#!/bin/sh\necho {{skillsDir}}\n', { mode: 0o755 });
+    // The empty-remote seed is the one path that copies a whole template.
+    const dir = path.join(root, 'seeded-bytes');
+    await fs.mkdir(dir, { recursive: true });
+    await buildSeedTree(customTemplate, [], ['admin@example.com'])(dir);
+
+    expect(await fs.readFile(path.join(dir, 'assets', '.logo.bin'))).toEqual(binary);
+    expect(norm(await fs.readFile(path.join(dir, 'scripts', 'run.sh'), 'utf8'))).toBe('#!/bin/sh\necho Skills\n');
+    if (process.platform !== 'win32') {
+      expect((await fs.stat(path.join(dir, 'scripts', 'run.sh'))).mode & 0o111).not.toBe(0);
+    }
+  });
+
+  it("declares a custom template's ignore file without the stale Skills/ rule it still ships", async () => {
+    // A KB with NO ignore file gets the template's copy — and a distribution's
+    // template may still carry the rule the previous release had. The on-disk
+    // reconciliation never runs on an absent file, so the declared content
+    // must arrive already reconciled.
+    const customTemplate = path.join(root, 'custom-template-stale');
+    await fs.mkdir(customTemplate, { recursive: true });
+    await fs.writeFile(path.join(customTemplate, 'AGENTS.md'), await template('AGENTS.md'), 'utf8');
+    await fs.writeFile(
+      path.join(customTemplate, '.bevelignore'),
+      '# custom\nMyStuff/\n# The shared-skills root is rendered by the Skills & Tools app, like {{pluginsDir}}/.\n{{skillsDir}}/\n',
+      'utf8',
+    );
+    const scaffold = await fullScaffold();
+    delete scaffold['.bevelignore'];
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()], customTemplate).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    const text = norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'));
+    expect(text).toContain('MyStuff/');
+    expect(text.split('\n').map((l) => l.trim())).not.toContain('Skills/');
+    expect(text).not.toContain('shared-skills root');
+  });
+
+  it("leaves an operator's !Skills/ negation alone — there is nothing of the platform's to remove", async () => {
+    const scaffold = await fullScaffold();
+    scaffold['.bevelignore'] = 'AGENTS.md\nPlugins/\n!Skills/\n';
+    await seedUpstream(scaffold);
+
+    await makeRunner([new TemplateFilesStep()]).runAll();
+
+    const dir = await checkout(DEFAULT_BRANCH);
+    expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe('AGENTS.md\nPlugins/\n!Skills/\n');
   });
 
   it('respects an explicit !AGENTS.md negation — hiding the doc is a default, not a mandate', async () => {
     // Appending the positive rule after the negation would WIN under ordered
     // matching and silently defeat the operator's stated choice to show it.
     const scaffold = await fullScaffold();
-    scaffold['.bevelignore'] = '# operator wants the doc visible\n!AGENTS.md\n';
+    scaffold['.bevelignore'] = '# operator wants the doc visible\n!AGENTS.md\nPlugins/\n';
     await seedUpstream(scaffold);
 
     await makeRunner([new TemplateFilesStep()]).runAll();
 
     const dir = await checkout(DEFAULT_BRANCH);
     expect(norm(await fs.readFile(path.join(dir, '.bevelignore'), 'utf8'))).toBe(
-      '# operator wants the doc visible\n!AGENTS.md\n',
+      '# operator wants the doc visible\n!AGENTS.md\nPlugins/\n',
     );
   });
 
@@ -294,11 +466,54 @@ describe('buildSeedTree', () => {
     expect(await fs.readFile(path.join(dest, 'docs/guide.md'), 'utf8')).toBe('guide');
     expect(await fs.readFile(path.join(dest, 'access.md'), 'utf8')).toBe('policy');
     // The generated paths — what the runner force-adds past a template .gitignore.
-    expect(generated.sort()).toEqual(['KnowledgeBase/.gitkeep', 'Plugins/.gitkeep', 'roles.yaml']);
+    expect(generated.sort()).toEqual(['KnowledgeBase/.gitkeep', 'Plugins/.gitkeep', 'Skills/.gitkeep', 'roles.yaml']);
     expect(await exists(dest, 'roles.yaml')).toBe(true);
   });
 });
 
+describe('PluginManifestsStep', () => {
+  it('writes plugin.json into legacy plugin folders on every branch, and leaves scopes and real plugins alone', async () => {
+    const scaffold = await fullScaffold();
+    await seedUpstream({
+      ...scaffold,
+      // Legacy shapes: access.md only; mcp.json only; a bare skill tree.
+      'Plugins/GTM/access.md': '---\n---\nread:\n  - everyone\n',
+      'Plugins/GTM/outreach/SKILL.md': '---\ndescription: x\n---\n',
+      'Plugins/Servers/mcp.json': '{"mcpServers":{}}',
+      'Plugins/Bare/deploy/SKILL.md': '---\ndescription: y\n---\n',
+      // Already a plugin, both shapes.
+      'Plugins/Modern/plugin.json': '{"name":"modern"}',
+      'Plugins/functional/cluster/example/plugin.bundle.json': '{"name":"example"}',
+      // A scope with rules of its own above a bundle: not a plugin.
+      'Plugins/functional/access.md': '---\n---\nread:\n  - everyone\n',
+      // Nothing plugin-shaped at all.
+      'Plugins/notes/README.md': 'just a folder',
+    });
+
+    await makeRunner([new PluginManifestsStep()]).runAll();
+
+    for (const branch of PROTECTED) {
+      const dir = await checkout(branch);
+      for (const legacy of ['GTM', 'Servers', 'Bare']) {
+        const manifest = JSON.parse(await fs.readFile(path.join(dir, `Plugins/${legacy}/plugin.json`), 'utf8'));
+        expect(manifest.name).toBe(legacy.toLowerCase());
+      }
+      expect(await exists(dir, 'Plugins/functional/plugin.json')).toBe(false);
+      expect(await exists(dir, 'Plugins/notes/plugin.json')).toBe(false);
+      expect(await fs.readFile(path.join(dir, 'Plugins/Modern/plugin.json'), 'utf8')).toBe('{"name":"modern"}');
+    }
+    const dir = await checkout(DEFAULT_BRANCH);
+    const log = (await git(dir, ['log', '-1', '--format=%B'])).trim();
+    expect(log).toContain('Add plugin manifests to 3 legacy plugin folders');
+    expect(log).toContain('Plugins/GTM: plugin.json written');
+
+    // Idempotent: nothing left to write on the next boot.
+    await makeRunner([new PluginManifestsStep()]).runAll();
+    const again = await checkout(DEFAULT_BRANCH);
+    expect((await git(again, ['rev-list', '--count', 'HEAD'])).trim()).toBe('2'); // init + one migration commit
+  });
+});
+
 describe('GroupsToPluginsStep', () => {
   it('migrates a Groups/ tree to the Plugins layout — on the protected branches AND a draft', async () => {
     const seed = await seedUpstream({

package/src/modules/workspace/startup/steps/plugin-manifests.step.ts

@@ -0,0 +1,129 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  HEXIS_EXTENSION_NS,
+  PLUGINS_DIR,
+  PLUGIN_MANIFEST_FILE,
+  PLUGIN_MCP_FILE,
+  PLUGIN_SKILLS_DIR,
+  renderPluginManifest,
+} from '@bevel-software/platform-shared';
+import { BUNDLE_FILE } from '../../../plugins/discovery/bundle-dialect/bundle.source.js';
+import { isAbsence } from '../../../../shared/fs-errors.js';
+import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+
+/**
+ * Give every legacy plugin folder its manifest, as an {@link OnServerStart}
+ * step.
+ *
+ * A plugin IS a folder carrying `plugin.json` (or a `plugin.bundle.json`, the
+ * read-only customer dialect) — discovery reads nothing else, at any depth.
+ * Folders from before the manifest existed have `access.md`, an `mcp.json`,
+ * a `skills/` tree or `.tool` manuals and no `plugin.json` beside them; the
+ * old scanners read those by position (directly under the plugins root),
+ * and this step is what retires that rule: it writes the minimal manifest
+ * into each such folder, once, so the position never has to mean anything
+ * again.
+ *
+ * WHICH folders: walk the plugins root; a folder holding either file is a
+ * plugin and is not entered. Any other folder is entered first. A folder
+ * DIRECTLY under the root — the only place the legacy layout ever put a
+ * plugin — becomes one when nothing plugin-shaped lives beneath it and its
+ * own content is legacy content: a scope folder (the dialect's
+ * `plugins/functional/…`) can carry an `access.md` of its own and must stay
+ * a scope, and a skill folder inside a legacy plugin must not become a
+ * plugin of its own. "Legacy content" is the set of things provisioning and
+ * the old migration ever put in a plugin folder: `access.md`, `mcp.json`,
+ * `skills/`, the hexis extension directory, a `.tool` file, or a `SKILL.md`
+ * anywhere beneath (the pre-`skills/` shape).
+ *
+ * Every branch, drafts included, like the Groups→Plugins migration and for
+ * the same reason: a draft migrated alongside its target diffs by the user's
+ * own changes only. Idempotent: a folder that has its manifest is skipped.
+ */
+export class PluginManifestsStep implements OnServerStart {
+  readonly name = 'plugin-manifests';
+
+  async run(ctx: ServerStartContext): Promise<StepResult> {
+    for (const branch of await ctx.allBranches()) {
+      await addManifests(branch);
+    }
+    return { outcome: 'ok' };
+  }
+}
+
+async function addManifests(branch: KbBranch): Promise<void> {
+  const repoDir = await branch.repoDir();
+  const root = path.join(repoDir, PLUGINS_DIR);
+  const added: string[] = [];
+
+  /** Resolves to how many plugins sit at or beneath `dir`. */
+  const visit = async (dir: string, rel: string): Promise<number> => {
+    if (rel && ((await isFile(path.join(dir, PLUGIN_MANIFEST_FILE))) || (await isFile(path.join(dir, BUNDLE_FILE))))) {
+      return 1;
+    }
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      // Absence is the plugins root not existing yet; anything else must stop
+      // the boot rather than quietly leave legacy plugins without manifests.
+      if (isAbsence(err)) return 0;
+      throw err;
+    }
+    let beneath = 0;
+    for (const entry of entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'))) {
+      beneath += await visit(path.join(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
+    }
+    if (beneath > 0 || !rel || rel.includes('/')) return beneath;
+    if (!(await looksLikeLegacyPlugin(dir, entries))) return 0;
+    const manifestRel = `${PLUGINS_DIR}/${rel}/${PLUGIN_MANIFEST_FILE}`;
+    branch.write(manifestRel, renderPluginManifest(path.posix.basename(rel)));
+    added.push(rel);
+    return 1;
+  };
+
+  await visit(root, '');
+  if (added.length === 0) return;
+  branch.note(`Add plugin manifests to ${added.length === 1 ? 'a legacy plugin folder' : `${added.length} legacy plugin folders`}`);
+  for (const rel of added) branch.note(`${PLUGINS_DIR}/${rel}: ${PLUGIN_MANIFEST_FILE} written`);
+}
+
+async function looksLikeLegacyPlugin(dir: string, entries: import('node:fs').Dirent[]): Promise<boolean> {
+  for (const entry of entries) {
+    if (entry.isFile() && (entry.name === 'access.md' || entry.name === PLUGIN_MCP_FILE || entry.name.toLowerCase().endsWith('.tool'))) {
+      return true;
+    }
+    if (entry.isDirectory() && (entry.name === PLUGIN_SKILLS_DIR || entry.name === HEXIS_EXTENSION_NS)) return true;
+  }
+  return hasSkillBeneath(dir);
+}
+
+/** The pre-`skills/` shape: `Plugins/<Plugin>/<skill>/SKILL.md`, at any depth. */
+async function hasSkillBeneath(dir: string): Promise<boolean> {
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isAbsence(err)) return false;
+    throw err;
+  }
+  if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) return true;
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith('.') && (await hasSkillBeneath(path.join(dir, entry.name)))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function isFile(abs: string): Promise<boolean> {
+  return fs.stat(abs).then(
+    (s) => s.isFile(),
+    (err: unknown) => {
+      if (isAbsence(err)) return false;
+      throw err; // a probe that fails for another reason is not "no manifest"
+    },
+  );
+}
+