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

package/migrations/meta/_journal.json

@@ -120,6 +120,13 @@
       "when": 1790933605784,
       "tag": "0016_pii_encryption",
       "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1791359019161,
+      "tag": "0017_atlassian_account_links",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.25.2",
+  "version": "0.27.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,6 +23,9 @@
     "src",
     "migrations",
     "kb-template",
+    "agent-guide",
+    "mcp-app",
+    "starter-packs",
     "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
@@ -52,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.25.2",
-    "@bevel-software/platform-shared": "0.25.2"
+    "@bevel-software/platform-shared": "0.27.0",
+    "@bevel-software/platform-mcp-core": "0.27.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/kb-layout-config.test.ts

@@ -5,15 +5,12 @@ import {
   KNOWLEDGE_BASE_DIR,
   PLUGINS_DIR,
   SKILLS_DIR,
-  agentsFilePointerSentence,
   configureKbLayout,
   currentKbLayout,
   isPlatformFile,
-  mentionsAgentsFile,
   platformFileNames,
   pluginOfPath,
   renderKbLayoutPlaceholders,
-  retargetAgentsFilePointer,
   reservedRootDirNames,
   validateAgentsFileName,
   validateKbLayout,
@@ -193,106 +190,19 @@ describe('KB layout — the agent guide\'s file name', () => {
     expect(renderKbLayoutPlaceholders('see {{agentsFile}}', DEFAULT_KB_LAYOUT)).toBe('see AGENTS.md');
   });
 
-  test('the platform-file gate follows the name: ours is managed, theirs is content', () => {
-    expect(platformFileNames(DEFAULT_KB_LAYOUT)).toEqual([
-      'access.md',
-      'roles.yaml',
-      '.bevelignore',
-      'AGENTS.md',
-    ]);
-    expect(platformFile('AGENTS.md')).toBe(true);
-
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(platformFileNames(currentKbLayout())).toEqual(['access.md', 'roles.yaml', '.bevelignore', 'HEXIS.md']);
-    // The guide the platform writes is immovable and undeletable…
-    expect(platformFile('HEXIS.md')).toBe(true);
-    // …and the customer's own AGENTS.md is a page like any other.
+  test('the guide is no platform file under any name: a root AGENTS.md is the organisation\'s own page', () => {
+    // The platform's guide is served from code and never written to the
+    // repository, so nothing under its name is the platform's to protect.
+    expect(platformFileNames(DEFAULT_KB_LAYOUT)).toEqual(['access.md', 'roles.yaml', '.bevelignore']);
     expect(platformFile('AGENTS.md')).toBe(false);
-    // Still root-only, as `roles.yaml` is: a nested copy is content.
-    expect(platformFile('KnowledgeBase/HEXIS.md')).toBe(false);
-  });
+    expect(platformFile('roles.yaml')).toBe(true);
 
-  test('the pointer sentence is one sentence, naming the guide twice, from one place', () => {
-    expect(agentsFilePointerSentence('HEXIS.md')).toBe(
-      'Read [HEXIS.md](./HEXIS.md) before working in this knowledge base — ' +
-        "it is the platform's guide to its layout, files and rules.",
-    );
+    // A name a deployment saved for the written guide is a read alias now,
+    // not a file, and makes no platform file either.
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(agentsFilePointerSentence(currentKbLayout().agentsFile)).toContain('HEXIS.md');
-  });
-
-  /**
-   * A guide name is a FILE NAME: spaces, brackets, parentheses, `#` and `%`
-   * all pass `validateFilename`, and every one of them means something in an
-   * inline link. The label must not end early and the destination must still
-   * point at the file.
-   */
-  test('the pointer sentence links correctly for a name full of markdown punctuation', () => {
-    const name = 'Our [Agent] Guide (v2).md';
-    expect(validateGuideName(name)).toBeNull();
-    const sentence = agentsFilePointerSentence(name);
-    // The label cannot end early: the brackets in it are escaped…
-    expect(sentence).toContain('[Our \\[Agent\\] Guide (v2).md]');
-    // …and the destination is percent-encoded, parentheses included — a bare
-    // `)` would close the link half way through the name.
-    expect(sentence).toContain('(./Our%20%5BAgent%5D%20Guide%20%28v2%29.md)');
-    // The ordinary name reads as it always has — no escapes, nothing encoded.
-    expect(agentsFilePointerSentence('AGENTS.md')).toContain('[AGENTS.md](./AGENTS.md)');
-  });
-
-  test('the pointer sentence encodes a name that would otherwise open a URL fragment', () => {
-    // `#` is legal in a filename and opens a fragment in a URL: `./#2 Guide.md`
-    // links to the customer's OWN file with a fragment, not to the guide.
-    expect(validateGuideName('#2 Guide.md')).toBeNull();
-    expect(agentsFilePointerSentence('#2 Guide.md')).toContain('(./%232%20Guide.md)');
-    // `%` is legal too, and an unencoded one is a malformed escape.
-    expect(agentsFilePointerSentence('100%.md')).toContain('(./100%25.md)');
-  });
-
-  /**
-   * The startup step asks this before appending, and it has to recognise the
-   * sentence the LAST boot wrote — whose spelling of the name is escaped in
-   * the label and encoded in the destination. Asking for the raw name alone
-   * would append a second copy on every boot after the first.
-   */
-  test('a file already carrying the pointer sentence counts as mentioning the guide', () => {
-    for (const name of ['AGENTS.md', 'Our [Agent] Guide (v2).md', '#2 Guide.md', '100%.md']) {
-      const appended = `# Acme\n\n${agentsFilePointerSentence(name)}\n`;
-      expect(mentionsAgentsFile(appended, name), name).toBe(true);
-    }
-    // A file that says nothing about the guide still reads as silent…
-    expect(mentionsAgentsFile('# Acme\n\nWrite tickets in the present tense.\n', 'HEXIS.md')).toBe(false);
-    // …and the customer's own plain mention counts, in their own words.
-    expect(mentionsAgentsFile('See HEXIS.md for the platform.', 'HEXIS.md')).toBe(true);
-  });
-
-  /**
-   * A second rename. The sentence written for the previous guide points at a
-   * file that is no longer there, and the new name appears nowhere in the
-   * text — so it has to be recognised by its SHAPE and aimed again.
-   */
-  test('a pointer sentence the platform wrote is retargeted, whatever guide it named', () => {
-    for (const before of ['HEXIS.md', 'Our [Agent] Guide (v2).md', '#2 Guide.md']) {
-      const text = `# Acme\n\n${agentsFilePointerSentence(before)}\n`;
-      expect(retargetAgentsFilePointer(text, 'GUIDE.md'), before).toBe(
-        `# Acme\n\n${agentsFilePointerSentence('GUIDE.md')}\n`,
-      );
-    }
-    // Already aimed right: ours, and unchanged — which is not the same answer
-    // as "none of ours here", and the caller tells them apart.
-    const current = `# Acme\n\n${agentsFilePointerSentence('GUIDE.md')}\n`;
-    expect(retargetAgentsFilePointer(current, 'GUIDE.md')).toBe(current);
+    expect(platformFileNames(currentKbLayout())).toEqual(['access.md', 'roles.yaml', '.bevelignore']);
+    expect(platformFile('HEXIS.md')).toBe(false);
+    expect(platformFile('AGENTS.md')).toBe(false);
   });
 
-  test('leaves a file holding nothing of the platform\'s alone', () => {
-    // Null, not the text: there is nothing of ours to aim, so the caller goes
-    // on to ask whether the customer mentioned the guide themselves.
-    expect(retargetAgentsFilePointer('# Acme\n\nWrite tickets in the present tense.\n', 'GUIDE.md')).toBeNull();
-    // Their own link to their own file is not our sentence.
-    expect(retargetAgentsFilePointer('Read [notes](./notes.md) before working here.', 'GUIDE.md')).toBeNull();
-    // Our opening words, their sentence.
-    expect(
-      retargetAgentsFilePointer('Read [HEXIS.md](./HEXIS.md) when you have a moment.', 'GUIDE.md'),
-    ).toBeNull();
-  });
 });

package/src/__tests__/packaged-assets-ship.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir, defaultStarterPacksDir, mcpAppDir } from '../assets.js';
+
+/**
+ * Every asset folder this package reads at run time has to reach the places
+ * the package is shipped from: the npm tarball (`files` in package.json) and
+ * the Docker image (the runtime stage of the repository's Dockerfile, which
+ * copies each folder by name).
+ *
+ * The second list is the one nothing else checks. `agent-guide/` was added to
+ * `assets.ts` and to `files`, but not to the Dockerfile, and no test or CI job
+ * builds the image: the folder was simply absent from every image built from
+ * dev. It is read while the tool list is composed, so the first request for
+ * any tool on the deployment failed, and every agent surface with it
+ * (2026-10-06). A folder named here and missing from either list fails this
+ * test instead.
+ *
+ * `mcp-app/` was the same omission one release later — caught here rather
+ * than on a deployment. It holds the `ui://` view `resources/read` serves, so
+ * an image without it answered `tools/list` with no view on `open_page` and
+ * `resources/list` with nothing, and the page-in-chat quietly degraded to
+ * text on every real build.
+ */
+const packageRoot = fileURLToPath(new URL('../..', import.meta.url));
+const repoRoot = path.resolve(packageRoot, '..', '..');
+
+/** The folders assets.ts locates, as names under the package root. */
+const ASSET_DIRS = [
+  coreMigrationsDir(),
+  defaultKbTemplateDir(),
+  agentGuideDir(),
+  mcpAppDir(),
+  defaultStarterPacksDir(),
+].map((dir) =>
+  path.basename(dir),
+);
+
+describe('the asset folders this package reads at run time', () => {
+  it('are the four assets.ts names', () => {
+    expect(ASSET_DIRS.sort()).toEqual(['agent-guide', 'kb-template', 'mcp-app', 'migrations', 'starter-packs']);
+  });
+
+  it('exist in the source tree', () => {
+    for (const dir of ASSET_DIRS) {
+      expect(fs.statSync(path.join(packageRoot, dir)).isDirectory(), dir).toBe(true);
+    }
+  });
+
+  it('are in the npm tarball', () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')) as { files: string[] };
+    for (const dir of ASSET_DIRS) {
+      expect(pkg.files, `${dir} missing from package.json "files"`).toContain(dir);
+    }
+  });
+
+  it('are copied into the Docker image by the runtime stage', () => {
+    const dockerfile = fs.readFileSync(path.join(repoRoot, 'Dockerfile'), 'utf8');
+    for (const dir of ASSET_DIRS) {
+      const line = `COPY --from=builder /app/packages/core-backend/${dir} packages/core-backend/${dir}`;
+      expect(dockerfile, `Dockerfile does not copy ${dir} into the image`).toContain(line);
+    }
+  });
+});

package/src/assets.ts

@@ -3,8 +3,9 @@ import { fileURLToPath } from 'node:url';
 
 /**
  * Locations of the assets shipped INSIDE this package (`files` in
- * package.json): the squashed core migration history (`migrations/`) and the
- * KB seed template (`kb-template/`). Both live at the PACKAGE ROOT, and this
+ * package.json): the squashed core migration history (`migrations/`), the
+ * KB seed template (`kb-template/`) and the starter packs (`starter-packs/`).
+ * All live at the PACKAGE ROOT, and this
  * module is a direct child of either `src/` (in-repo / tsx) or `dist/`
  * (compiled) — so one `..` hop from the module URL reaches the package root
  * in BOTH layouts. Resolved lazily so bundlers that rewrite `import.meta.url`
@@ -23,3 +24,38 @@ export function coreMigrationsDir(): string {
 export function defaultKbTemplateDir(): string {
   return path.join(packageRoot(), 'kb-template');
 }
+
+/**
+ * The sections of the platform's agent guide, one markdown file each — the
+ * text `get_agent_guide` and a `read_file` of the guide's name serve, composed
+ * by `modules/agent-guide`. Beside `kb-template/` rather than under `src/`,
+ * so a build and the published source find it at the same place.
+ */
+export function agentGuideDir(): string {
+  return path.join(packageRoot(), 'agent-guide');
+}
+
+/**
+ * The MCP App views this deployment serves over `resources/read` — one static
+ * HTML file each, no build step. Beside `agent-guide/` and `kb-template/` for
+ * the same reason: a build and the published source find it at the same
+ * place, and `tsc` copies nothing that is not TypeScript.
+ *
+ * The backend serves these as BYTES and never imports frontend code — the
+ * view's whole job is to load the deployment's embed bundle into its own
+ * document (hosts forbid framing the deployment, see `mcp-app.ts`), where the
+ * app's renderers then draw the page.
+ */
+export function mcpAppDir(): string {
+  return path.join(packageRoot(), 'mcp-app');
+}
+
+/**
+ * The starter packs a new knowledge base may be filled from — one folder per
+ * team (`engineering/`, `sales/`, …), each a `pack.yaml` beside the pages and
+ * the plugin it adds (see `modules/onboarding/starter-packs.ts`). Beside
+ * `kb-template/` for the same reason: read at run time, shipped as files.
+ */
+export function defaultStarterPacksDir(): string {
+  return path.join(packageRoot(), 'starter-packs');
+}

package/src/core/__tests__/catalog-revision.test.ts

@@ -47,6 +47,14 @@ describe('catalogRevision', () => {
     );
   });
 
+  it('moves when an MCP App view changes by a byte, and not when the same view is read again', () => {
+    const view = { uri: 'ui://hexis/page.html', text: '<html>v1</html>' };
+    const base = catalogRevision([manualLine('serper')], [skill()], [view]);
+    expect(catalogRevision([manualLine('serper')], [skill()], [{ ...view }])).toBe(base);
+    expect(catalogRevision([manualLine('serper')], [skill()], [{ ...view, text: '<html>v2</html>' }])).not.toBe(base);
+    expect(catalogRevision([manualLine('serper')], [skill()], [])).not.toBe(base);
+  });
+
   describe('a manual added, changed or removed', () => {
     const base = catalogRevision([manualLine('serper')], []);
 
@@ -115,6 +123,8 @@ describe('GET /agent/catalog-revision', () => {
     skills: SkillSummary[];
     userId?: string | undefined;
     resolveUserEmail?: (userId: string) => Promise<string | undefined>;
+    /** The served views, or a manifest read that fails. */
+    mcpApps?: { manifest(): Promise<{ resources: { uri: string; text: string }[] }> };
   }): Promise<{
     url: string;
     catalogFingerprints: ReturnType<typeof vi.fn>;
@@ -132,6 +142,7 @@ describe('GET /agent/catalog-revision', () => {
           next();
         },
         resolveUserEmail: deps.resolveUserEmail ?? (async () => 'someone@example.com'),
+        ...(deps.mcpApps ? { mcpApps: deps.mcpApps } : {}),
       }),
     );
     http = app.listen(0);
@@ -174,6 +185,35 @@ describe('GET /agent/catalog-revision', () => {
     expect(catalogFingerprints).not.toHaveBeenCalled();
   });
 
+  it('folds the served MCP App views into the revision, so a changed view moves it', async () => {
+    const view = { uri: 'ui://hexis/page.html', text: '<html>v1</html>' };
+    const { url } = await mount({
+      manuals: [manualLine('serper')],
+      skills: [skill()],
+      userId: 'u1',
+      mcpApps: { manifest: async () => ({ resources: [view] }) },
+    });
+    const body = (await (await fetch(`${url}/agent/catalog-revision`)).json()) as { revision: string };
+    expect(body.revision).toBe(catalogRevision([manualLine('serper')], [skill()], [view]));
+    expect(body.revision).not.toBe(catalogRevision([manualLine('serper')], [skill()]));
+  });
+
+  it('answers the no-views revision when the manifest cannot be read, rather than failing', async () => {
+    const { url } = await mount({
+      manuals: [manualLine('serper')],
+      skills: [skill()],
+      userId: 'u1',
+      mcpApps: {
+        manifest: async () => {
+          throw new Error('the view file is gone');
+        },
+      },
+    });
+    const res = await fetch(`${url}/agent/catalog-revision`);
+    expect(res.status).toBe(200);
+    expect(((await res.json()) as { revision: string }).revision).toBe(catalogRevision([manualLine('serper')], [skill()]));
+  });
+
   it('does not fail the request when the email lookup throws', async () => {
     const { url } = await mount({
       manuals: [manualLine('serper')],

package/src/core/__tests__/gated-boot.test.ts

@@ -50,6 +50,7 @@ function bootable(runAll: () => Promise<void>) {
     } as BootableCore['kbStartupRunner'],
     workflowService: {
       closeChangeRequestsWithDeletedBranches: async () => 0,
+      tidyAfterSweep: async () => ({ closedEmpty: 0, removedLeftovers: 0 }),
     } as BootableCore['workflowService'],
     pluginJoinRequestJobs: { startSweeping() {} } as BootableCore['pluginJoinRequestJobs'],
     startupRetry: null,

package/src/core/__tests__/lifecycle.test.ts

@@ -453,6 +453,14 @@ describe('stopCore', () => {
             order.push('startupRetry.stop');
           },
         },
+        workflowService: {
+          stopTidying() {
+            order.push('workflowService.stopTidying');
+          },
+          async drainTidy() {
+            order.push('workflowService.drainTidy');
+          },
+        },
         db: {
           $client: {
             async end() {
@@ -473,8 +481,10 @@ describe('stopCore', () => {
       'backgroundJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
+      'workflowService.stopTidying',
       'backgroundJobs.drain',
       'agentUploadStore.drainSweep',
+      'workflowService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -515,8 +525,10 @@ describe('stopCore', () => {
     expect(g.order).toEqual([
       'backgroundJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
+      'workflowService.stopTidying',
       'backgroundJobs.drain',
       'agentUploadStore.drainSweep',
+      'workflowService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -530,8 +542,10 @@ describe('stopCore', () => {
       'backgroundJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
+      'workflowService.stopTidying',
       'backgroundJobs.drain',
       'agentUploadStore.drainSweep',
+      'workflowService.drainTidy',
       'db.end',
     ]);
   });

package/src/core/catalog-revision.ts

@@ -57,11 +57,19 @@ function skillFingerprint(s: SkillSummary): string {
 export function catalogRevision(
   manuals: readonly string[],
   skills: readonly SkillSummary[],
+  /**
+   * The MCP App views this deployment serves, by their bytes: a release that
+   * changes a view and nothing else must still move the revision, or a local
+   * server already running keeps serving the view it read at startup.
+   */
+  views: readonly { uri: string; text: string }[] = [],
 ): string {
   const lines = [
     ...[...manuals].sort(),
-    '\u0001', // separates the two lists, so a line can never migrate between them
+    '\u0001', // separates the lists, so a line can never migrate between them
     ...skills.map(skillFingerprint).sort(),
+    '\u0001',
+    ...views.map((v) => `${v.uri}\u0000${createHash('sha256').update(v.text).digest('hex')}`).sort(),
   ];
   return createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 32);
 }
@@ -82,6 +90,8 @@ export function createCatalogRevisionRoutes(deps: {
   manualAuth: RequestHandler;
   /** Connection-key/internal-token user id → email, for the per-caller ACL. */
   resolveUserEmail: (userId: string) => Promise<string | undefined>;
+  /** The MCP App views served; absent on a deployment that serves none. */
+  mcpApps?: { manifest(): Promise<{ resources: readonly { uri: string; text: string }[] }> };
 }): express.Router {
   const router = express.Router();
 
@@ -95,8 +105,11 @@ export function createCatalogRevisionRoutes(deps: {
       const [manuals, skills] = email
         ? await Promise.all([deps.toolManuals.catalogFingerprints(email), deps.skills.listSkills(email)])
         : [[], []];
+      // A manifest that cannot be read counts as no views, which is also what
+      // the MCP endpoint serves in that state.
+      const views = deps.mcpApps ? ((await deps.mcpApps.manifest().catch(() => null))?.resources ?? []) : [];
       res.json({
-        revision: catalogRevision(manuals, skills),
+        revision: catalogRevision(manuals, skills, views),
         tools: manuals.length,
         skills: skills.length,
       });

package/src/core/core-ports.ts

@@ -9,6 +9,7 @@ import type { IErasureParticipant } from '../modules/auth/account-erasure.servic
 import type { IAccountAdmission } from '../modules/auth/account-admission.js';
 import type { IWriteAccess } from '../modules/write-access/write-access.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
+import type { AgentGuideHook } from '../modules/agent-guide/agent-guide.js';
 
 /**
  * Every seam the enterprise overlay can fill in the CORE composition
@@ -100,6 +101,16 @@ export interface CorePorts {
    * contract each step signs up to). Core default: `[]`.
    */
   kbStartupSteps?: readonly OnServerStart[];
+  /**
+   * THIS distribution's say over the agent guide — the text `get_agent_guide`
+   * and a `read_file` of the guide's name serve. Called with core's sections
+   * and the layout in effect on every composition; returns the sections the
+   * guide is made of, so a distribution appends its own, replaces one of
+   * core's by id, or drops one, and every change core makes to the rest still
+   * reaches it. Core default: core's sections as they are. See
+   * `modules/agent-guide`.
+   */
+  agentGuide?: AgentGuideHook;
   /**
    * Mirror this composition's branch model and knowledge-base layout onto the
    * shared package's PROCESS-WIDE live bindings (`DEFAULT_BRANCH`,

package/src/core/create-core-server.ts

@@ -8,6 +8,7 @@ import {
   createAgentUploadRoutes,
   isAgentUploadRawBodyPath,
 } from '../modules/workspace/agent-upload.routes.js';
+import { createAgentDownloadRoutes } from '../modules/workspace/agent-download.routes.js';
 import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals.middleware.js';
 import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
@@ -26,7 +27,10 @@ import {
   registerToolManualsTools,
 } from '../modules/tool-manuals/index.js';
 import { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
+import { changeRequestScope, registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+import { createOnboardingRoutes } from '../modules/onboarding/onboarding.routes.js';
 import { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
+import { registerAgentGuideTool } from '../modules/agent-guide/index.js';
 import { RECOVERY_BOT_EMAIL } from '../modules/workflow/recovery-bot.js';
 import {
   registerSkillsTools,
@@ -53,6 +57,7 @@ import { createUpdateCheckRoutes } from '../modules/update-check/update-check.ro
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
 import { createConnectionKeysAdminRoutes } from '../modules/tool-auth/connection-keys-admin.routes.js';
 import { createAuditRoutes } from '../modules/audit/audit.routes.js';
+import { createAgentConnectionRoutes } from '../modules/audit/agent-connection.routes.js';
 import { createAgentRestAuditMiddleware } from '../modules/audit/agent-rest-audit.middleware.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../modules/tool-manuals/tool-manuals.contract.js';
 import { createSetupRoutes, isComplete } from '../modules/settings/setup.routes.js';
@@ -77,6 +82,10 @@ import { createReadiness } from './readiness.js';
 import { createAgentInstructionsRoutes } from '../modules/agent-instructions/index.js';
 import type { CoreServices } from './create-core-services.js';
 import { createWriteAccessRoutes, createWriteGateMiddleware } from '../modules/write-access/write-access.js';
+import { createEmbedRoutes, createEmbedLinkRoutes } from '../modules/embed/embed.routes.js';
+import { registerEmbedTools } from '../modules/embed/embed.tools.js';
+import { createMcpAppRoutes } from '../modules/embed/mcp-app.routes.js';
+import { isSandboxReachableOrigin } from '../modules/embed/mcp-app.js';
 
 type ExpressApp = ReturnType<typeof express>;
 
@@ -84,6 +93,11 @@ type ExpressApp = ReturnType<typeof express>;
  * The context handed to {@link ServerExtensions.tools}: everything an overlay
  * needs to register its own tool defs + endpoint routes on the unified tool
  * surface, exactly like the core modules do.
+ *
+ * A tool that works on a branch declares it on its `toolDef` (`branch:
+ * 'required'` or, read-only tools only, `'defaults-to-default-branch'`), and
+ * `toolHandler` resolves the branch before the tool runs — see "The branch"
+ * in `modules/tool-helpers/index.ts`.
  */
 export interface ToolSurfaceCtx {
   registry: CoreServices['toolRegistry'];
@@ -455,8 +469,35 @@ export async function createCoreServer(
   // every save surface (agent write tools, the app's PUT /file) and on
   // `get_skill`. Warnings only; it never refuses a save.
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
-  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore);
+  // `delete_branch` sees change requests as `get_change_request` does.
+  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee);
+  // The five read tools over change requests. Separate from the workflow tools
+  // because they are the only ones that gate their whole payload on the
+  // caller's read access, so they take the access service and nothing else.
+  registerChangeRequestReadTools(core.toolRegistry, toolsRouter, ta, th, core.accessControl, core.kb);
+  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide, core.agentDownloadStore, core.starterPackService, core.disk);
+  // `open_page` — the knowledge-base page shown inside a chat. Registered
+  // here, on the same router as the file tools, because it answers with
+  // `read_file`'s own read: the read hook, the access gate and the
+  // not-found refusal come from that registration rather than from a copy.
+  registerEmbedTools(core.toolRegistry, toolsRouter, ta, th, {
+    embedService: core.embedService,
+    kb: core.kb,
+    readForTool: workspaceTools.readForTool,
+    // A host's https sandbox cannot load from a plain-http deployment, so
+    // the tool answers the text and the app address and says so.
+    canBeReached: () => isSandboxReachableOrigin(core.config.publicFrontendUrl),
+    appUrlFor: (repoRelative, slug) => core.embedService.appUrlFor(repoRelative, slug),
+    // The read is `read_file`'s, so the notes a deployment registers for the
+    // gated tools reach this one as well.
+    notes: agentAccessGate.notes,
+  });
+  // The app manifest and the view bytes, for the LOCAL MCP server: it bridges
+  // a host to this deployment over HTTP and has no other way to learn which
+  // tools carry a view. Same router, same `manualAuth` as `all-tools`.
+  toolsRouter.use(createMcpAppRoutes(core.mcpAppService, core.manualAuthMiddleware));
+  // The guide on its own, beside the file tools that serve it by name.
+  registerAgentGuideTool(core.toolRegistry, toolsRouter, ta, th, core.agentGuideSections);
   // The agent upload route, on the same router as the tool endpoints so it
   // mounts ahead of the JWT `/api` mounts below — but WITHOUT `toolAuth`: its
   // whole credential is the single-use token in its path, which is the point
@@ -464,16 +505,23 @@ export async function createCoreServer(
   // no workspace and writes into none; every access, platform-file and branch
   // rule is applied later by `apply_file_upload`.
   toolsRouter.use(createAgentUploadRoutes({ uploads: core.agentUploadStore }));
+  // Its outgoing twin, mounted the same way and for the same reason: the
+  // one-time link is the whole credential an agent's `curl` carries. Every
+  // file behind it was judged when `request_file_download` issued it.
+  toolsRouter.use(createAgentDownloadRoutes({ downloads: core.agentDownloadStore, identify: core.agentDownloadFetcher }));
   registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService, allowedToolsChecker);
   // Definitions only: the endpoints they describe are the app's own plugin
   // creation routes, mounted below behind the key-or-session gate.
-  registerPluginsTools(core.toolRegistry);
+  registerPluginsTools(core.toolRegistry, core.kb);
   registerToolManualsTools(core.toolRegistry, toolsRouter, ta, th, core.toolManualService, {
     accessControl: core.accessControl,
     // The vault satisfies the module's local VariableStatusPort — `list_tool_setup`
     // reports configuration booleans only; secret values never ride through tools.
     variableStatus: core.secretsVaultService,
     kb: core.kb,
+    // What the proxy's schema check found when each server's tools were last
+    // loaded — reported to a caller who may write the tool, nobody else.
+    hiddenTools: core.mcpService.hiddenTools,
   });
   // Overlay tool registrations (defs + module-hosted endpoints).
   ext.tools?.({
@@ -517,6 +565,9 @@ export async function createCoreServer(
     skills: core.skillService,
     manualAuth: core.manualAuthMiddleware,
     resolveUserEmail: async (userId) => (await core.authService.getUserById(userId))?.email,
+    // The views move the revision too: a release that changes a view and no
+    // manual would otherwise leave a running local server on the old one.
+    mcpApps: core.mcpAppService,
   }));
   // The only core route that returns secret VALUES: a local `.tool`'s declared
   // variables, for the local MCP server that will execute it. It re-reads the
@@ -543,6 +594,12 @@ export async function createCoreServer(
   // Non-JWT overlay surfaces that sit between the tools router and the
   // JWT-protected `/api` routes (LLM proxy, embed, upload — see the phase
   // doc on ServerExtensions.postTools).
+  // The embed surface, ahead of every JWT mount and of the static
+  // catch-all: its data routes authenticate by the embed token ALONE (a
+  // session reaching them must be refused, not honoured), and the two SPA
+  // routes need their framing headers stamped before `index.html` is served.
+  app.use(createEmbedRoutes(core.embedService));
+
   ext.postTools?.(app, core);
 
   // The plugin creation doors — `POST /api/plugins`, `POST /api/plugins/personal`
@@ -718,6 +775,18 @@ export async function createCoreServer(
     core.authMiddleware,
     createAuditRoutes(core.agentAuditService, core.externalApiKeyService, core.adminAccess),
   );
+  // The onboarding's "is your agent connected yet?" — the caller's own
+  // agents only, read off the same connections and keys the Audit log lists.
+  app.use('/api', core.authMiddleware, createAgentConnectionRoutes(core.agentAuditService));
+  // "What does your team do?" — the starter-pack question a new knowledge
+  // base's admin is asked, and the pack it adds (admin-gated inside).
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createOnboardingRoutes(core.starterPackService, async (req) =>
+      req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null,
+    ),
+  );
   // First-run setup. Mounted with the other authed routes but touching NO
   // workspace — it has to work on a deployment that has no knowledge base yet,
   // which is the whole reason it exists. The startup runner rides along for
@@ -810,6 +879,12 @@ export async function createCoreServer(
   }));
 
   // JWT-protected overlay routes.
+  // Linking an outside account to the signed-in user, and managing those
+  // links. Under the JWT middleware, deliberately: the link acts AS the
+  // session, which is exactly why the page it is called from refuses every
+  // framing ancestor.
+  app.use('/api', core.authMiddleware, createEmbedLinkRoutes(core.embedService));
+
   ext.authed?.(app, core);
 
   // In production, serve the frontend static build