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

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

@@ -17,6 +17,10 @@ import { getDb, type Database } from '../modules/database/connection.js';
 import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
 import { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import { AccountLinkService } from '../modules/embed/account-link.service.js';
+import { EmbedService } from '../modules/embed/embed.service.js';
+import { McpAppService, type IMcpAppService } from '../modules/embed/mcp-app.js';
+import { createFileReaderRegistry } from '../modules/workspace/file-readers/file-reader.registry.js';
 import { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
 import { KbStartupRunner } from '../modules/workspace/startup/kb-startup-runner.js';
 import { GroupsToPluginsStep } from '../modules/workspace/startup/steps/groups-to-plugins.step.js';
@@ -26,7 +30,7 @@ import { PersonalSpacesStep } from '../modules/workspace/startup/steps/personal-
 import { TemplateFilesStep } from '../modules/workspace/startup/steps/template-files.step.js';
 import { RolesYamlStep } from '../modules/workspace/startup/steps/roles-yaml.step.js';
 import { buildSeedTree } from '../modules/workspace/startup/steps/seed-tree.js';
-import { DeploymentSettingsService } from '../modules/settings/deployment-settings.service.js';
+import { DeploymentSettingsService, retireMergedBranchesOn } from '../modules/settings/deployment-settings.service.js';
 import { KbSyncService } from '../modules/kb-sync/kb-sync.service.js';
 import { NodeFs } from '../modules/kb-fs/node-fs.js';
 import { assertKbDirNameFree } from '../modules/kb-fs/repo-path.js';
@@ -55,17 +59,21 @@ function parseDomainList(raw: string): string[] {
 }
 import { SpillStore } from '../modules/workspace/spill-store.js';
 import { AgentUploadStore, assertUploadsRootOutsideWorkspaces } from '../modules/workspace/agent-upload.store.js';
+import { AgentDownloadStore, type IAgentDownloadStore } from '../modules/workspace/agent-download.store.js';
+import { createDownloadFetcherIdentifier } from '../modules/workspace/agent-download.routes.js';
+import type { Request } from 'express';
 import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
 import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
-import { createAuthMiddleware } from '../modules/auth/auth.middleware.js';
+import { createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
 import { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
 import { CreatorAccessService } from '../modules/access/creator-access.js';
 import { ChangeReadGate } from '../modules/access/change-read-gate.js';
 import { GroupsAdminService } from '../modules/access/groups-admin.service.js';
 import { UserAccessRemovalService } from '../modules/access/user-access-removal.service.js';
+import { makeRolesYamlWriteValidator } from '../modules/access-model/roles-yaml-guard.js';
 import { PendingSkillsService, SkillService } from '../modules/skills/index.js';
 import { PendingToolsService, ToolManualService } from '../modules/tool-manuals/index.js';
 import { McpServerEditService } from '../modules/tool-manuals/mcp-server-edit.service.js';
@@ -110,6 +118,7 @@ import { ReviewWorkflowService } from '../modules/workflow/review-workflow/revie
 import { FileLockService } from '../modules/workflow/file-lock.service.js';
 import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
 import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
+import { StarterPackService } from '../modules/onboarding/starter-pack.service.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
 import { PendingCommitsService } from '../modules/workflow/pending-commits.service.js';
@@ -132,12 +141,19 @@ import {
 } from '../modules/tool-auth/internal-token.service.js';
 import {
   createToolAuthMiddleware,
+  createTokenVerifier,
   createManualAuthMiddleware,
 } from '../modules/tool-auth/tool-auth.middleware.js';
 import { unmeteredLlmUsage, type ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
 import { McpService } from '../modules/mcp/mcp.service.js';
 import { AgentAuditService, retentionDaysFrom } from '../modules/audit/agent-audit.service.js';
 import { readAgentPreamble, type AgentPreambleReader } from '../modules/agent-instructions/index.js';
+import {
+  agentGuideSections,
+  joinGuideSections,
+  type AgentGuideReader,
+  type AgentGuideSectionsReader,
+} from '../modules/agent-guide/index.js';
 import { createMcpAuthMiddleware } from '../modules/mcp/mcp-auth.middleware.js';
 import { BevelOAuthProvider } from '../modules/mcp/oauth/bevel-oauth-provider.js';
 import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
@@ -223,6 +239,14 @@ export interface CoreServices {
   spillStore: SpillStore;
   /** The bytes an agent uploaded, held until `apply_file_upload` lands them or their token expires. */
   agentUploadStore: AgentUploadStore;
+  /** The bytes `request_file_download` captured, held until their one-time link is fetched or expires. */
+  agentDownloadStore: IAgentDownloadStore;
+  /**
+   * Every user a download fetch identifies itself as, by its bearer and its
+   * session cookie — none when it carries none that verifies — so the
+   * download route can refuse a link presented by someone it was not issued to.
+   */
+  agentDownloadFetcher: (req: Request) => Promise<string[]>;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
@@ -239,11 +263,24 @@ export interface CoreServices {
    * and `GET /api/agent/instructions`. See modules/agent-instructions.
    */
   readAgentPreamble: AgentPreambleReader;
+  /**
+   * Composes the platform's agent guide for the layout in effect, through
+   * the distribution's hook when it passed one: what `get_agent_guide` and a
+   * `read_file` of the guide's name answer. See modules/agent-guide.
+   */
+  agentGuide: AgentGuideReader;
+  /** The same guide as its sections, each with its title — what `get_agent_guide` lists and serves one of. */
+  agentGuideSections: AgentGuideSectionsReader;
   mcpServerEditService: McpServerEditService;
   /** Deleting one tool — the owner's verb (see ToolDeleteService). */
   toolDeleteService: ToolDeleteService;
   pluginIndexService: PluginIndexService;
   pluginProvisionService: PluginProvisionService;
+  /**
+   * "What does your team do?" — the starter pack a new knowledge base's admin
+   * may fill it from, and the record of what was chosen. See modules/onboarding.
+   */
+  starterPackService: StarterPackService;
   joinRequestsService: JoinRequestsService;
   /**
    * Records a join request and finishes it in the background. Its `sweep()`
@@ -321,6 +358,14 @@ export interface CoreServices {
   connectionProbeService: ConnectionProbeService;
   externalApiKeyService: ExternalApiKeyService;
   internalTokenService: InternalTokenService;
+  /**
+   * The embed surface: the token-minted page a chat host frames, and the
+   * account links that let an outside identity reach it. Exposed so an
+   * overlay can mint for its own consumers and register a node-id resolver.
+   */
+  embedService: EmbedService;
+  /** The MCP Apps this deployment serves — the `open_page` view and its sandbox metadata. */
+  mcpAppService: IMcpAppService;
   mcpService: McpService;
   mcpAuthMiddleware: ReturnType<typeof createMcpAuthMiddleware>;
   mcpOAuthProvider: BevelOAuthProvider;
@@ -606,10 +651,7 @@ export async function createCoreServices(
     // backfill would walk a tree still missing those manifests.
     new PluginDisplayNamesStep(disk, kb),
     new PersonalSpacesStep(disk, kb),
-    // A getter, not a value: the step is built here, while the process may
-    // still hold the defaults, and the save that completes first-run setup
-    // applies the admin's answer afterwards.
-    new TemplateFilesStep(disk, kb, extraDirs, () => settings.resolveAgentsFileLink()),
+    new TemplateFilesStep(disk, kb, extraDirs),
     new RolesYamlStep(disk, [config.adminEmail]),
     ...(ports.kbStartupSteps ?? []),
   ];
@@ -674,6 +716,29 @@ export async function createCoreServices(
     publicBaseUrl: config.publicBackendUrl,
     tokenPrefix: config.uploadTokenPrefix,
   });
+  // The way OUT: bytes `request_file_download` captured, held beside the
+  // upload root — outside every workspace, for the same reason — until their
+  // one-time link is fetched or expires.
+  const agentDownloadsRoot = path.resolve(config.agentUploadsRoot, '..', 'agent-downloads');
+  // An upload root that is itself named `agent-downloads` would make the two
+  // stores one directory, each sweeping the other's files.
+  if (agentDownloadsRoot === path.resolve(config.agentUploadsRoot)) {
+    throw new Error(
+      'AGENT_UPLOADS_ROOT must not be a directory named `agent-downloads`: that name, beside it, is the agent download root.',
+    );
+  }
+  await assertUploadsRootOutsideWorkspaces(agentDownloadsRoot, config.workspacesRoot, {
+    name: 'The agent download root (`agent-downloads`, beside AGENT_UPLOADS_ROOT)',
+    why:
+      'captured download bytes wait there for their one-time links, so a root inside a workspace would let the ' +
+      'file tools read them. Point AGENT_UPLOADS_ROOT at a directory whose parent is outside WORKSPACES_ROOT.',
+  });
+  const agentDownloadStore = new AgentDownloadStore({
+    root: agentDownloadsRoot,
+    publicBaseUrl: config.publicBackendUrl,
+    // `<tenant>-down_`: recognisable by shape beside the upload token.
+    tokenPrefix: config.uploadTokenPrefix.replace(/up_$/, 'down_'),
+  });
   // Office-document/PDF text extraction for `read_file`/`grep`, cached by
   // content hash beside the workspaces root (see `DocExtractionCache`).
   const docExtractService = new DocExtractService(config.docExtractCacheRoot);
@@ -858,6 +923,9 @@ export async function createCoreServices(
     // it reach every hook point.
     workflowHooks,
   );
+  // The leftover-branch cleanup asks the Deployment page at every round, so
+  // switching it off there applies without a restart.
+  workflowService.leftoverCleanupEnabled = () => retireMergedBranchesOn(settings.resolve('retireMergedBranches'));
 
   // Join requests: derived entirely from two copies of a plugin's `access.md`
   // (the request's branch vs the default branch), so it holds no state — it
@@ -1042,6 +1110,27 @@ export async function createCoreServices(
     [config.adminEmail],
   );
 
+  // The starter-pack question: one commit on the default branch through the
+  // same batch write the roles admin uses, the choice kept as a deployment
+  // setting. Read by its routes and by `start_session`'s first-run note.
+  const starterPackService = new StarterPackService({
+    packsDir: config.starterPacksDir,
+    kb,
+    workspaceService,
+    workflow: workflowService,
+    adminAccess,
+    settings,
+    accessControl,
+    disk,
+    pluginSource,
+    pluginLocks: pluginProvisionService,
+    events: eventBus,
+    fileChanges: fileChangeNotifier,
+    // Its own lock: one starter-pack choice at a time, a concern no other
+    // service's mutex serialises.
+    choosing: new WorkspaceMutex(),
+  });
+
   // In-app update check: lazily compares the running release version against
   // the newest published GitHub release, only when an admin's browser asks —
   // no timers, so a deployment nobody looks at makes zero calls. The flag
@@ -1141,9 +1230,13 @@ export async function createCoreServices(
   // Connection keys also come as GitHub-shaped links (`gho_…`, kind
   // `github-link`): the same key, minted by the marketplace facade below when
   // a person connects an account on claude.ai, told apart by its stored kind.
-  const externalApiKeyService = new ExternalApiKeyService(db, config.externalApiKeyPrefix, {
-    [GITHUB_LINK_KEY_KIND]: GITHUB_LINK_KEY_SPEC,
-  });
+  const externalApiKeyService = new ExternalApiKeyService(
+    db,
+    config.externalApiKeyPrefix,
+    { [GITHUB_LINK_KEY_KIND]: GITHUB_LINK_KEY_SPEC },
+    // A key's first use tells its owner's open tabs that the agent arrived.
+    eventBus,
+  );
 
   // The facade that lets products which sync marketplaces only from a GitHub
   // Enterprise Server (claude.ai, Cowork) add the per-user marketplace:
@@ -1168,6 +1261,12 @@ export async function createCoreServices(
   // the proxy below composes in-process per request; the agent-facing route
   // serves the same composition to the local bridge and the frontend card.
   const readPreamble: AgentPreambleReader = () => readAgentPreamble(workspaceService, kb, disk);
+  // The guide every agent is told to read first, composed when asked for —
+  // the layout is read per call, so a name the setup save applies lands
+  // without a restart, and the distribution's hook sees every composition.
+  const agentGuideSectionsReader: AgentGuideSectionsReader = () =>
+    agentGuideSections(kb.layout, ports.agentGuide, { kbDirName });
+  const agentGuide: AgentGuideReader = async () => joinGuideSections(await agentGuideSectionsReader());
   // The Audit log. Records through the proxy below (every call an external
   // agent makes), reads keys through the key service so their shape is
   // defined once, and prunes past the retention setting — read per sweep, so
@@ -1175,6 +1274,34 @@ export async function createCoreServices(
   const agentAuditService = new AgentAuditService(db, externalApiKeyService, () =>
     retentionDaysFrom(settings.resolve('auditRetentionDays')),
   );
+  // The embed surface. It reads files through the workspace service and
+  // judges them with the same access resolver the app file page uses, so what
+  // a reader may see and change inside a chat is what they may see and change
+  // in the app — never a second answer to the same question.
+  const embedService = new EmbedService(
+    // The RESOLVED checkout folder, not the env's: `config.kbDirName` is only
+    // the environment value, empty on a deployment that took the default or
+    // named it in setup, and every path the embed builds starts with it.
+    { ...config, kbDirName },
+    kb,
+    workspaceService,
+    accessControl,
+    authService,
+    workflowService,
+    gitService,
+    new AccountLinkService(db),
+    // The SAME extension-to-reader registry `read_file` dispatches on, so the
+    // embed answer to "is this text, or bytes a renderer fetches?" cannot
+    // disagree with what a read of the file returns.
+    createFileReaderRegistry(docExtractService),
+    // The SAME pre-disk gate the file editor and the agent tools run: a
+    // `roles.yaml` that would not parse is refused before it is written, from
+    // a chat exactly as from the app.
+    makeRolesYamlWriteValidator(kbDirName),
+  );
+  // The `ui://` view `open_page` carries, with the one origin it may frame:
+  // this deployment own public origin.
+  const mcpAppService = new McpAppService({ publicFrontendUrl: config.publicFrontendUrl });
   const mcpService = new McpService(
     {
       // Loopback to our own REST tool surface — 127.0.0.1 (not localhost) to pin
@@ -1208,12 +1335,20 @@ export async function createCoreServices(
     (bearer) => mcpOAuthProvider.revokeByAccessToken(bearer),
     // Every attributable call lands in the Audit log through this.
     agentAuditService,
+    // The views the endpoint serves over resources/read, and the tools that
+    // carry them.
+    mcpAppService,
   );
   // A changed secret invalidates what the proxy built from the old value for
   // that user (null = shared secret → everyone): remembered manual failures,
   // so a just-repaired credential is retried on the very next request instead
   // of waiting out the failure memo's TTL, and pooled downstream connections.
   secretsVaultService.onMutation((changedUserId) => mcpService.onSecretsChanged(changedUserId));
+  // The proxy is the one place a connected server's tools are loaded, so it is
+  // the one place their schemas are checked — and the tool catalog is where the
+  // people who manage a server read what it found. Setter injection, like the
+  // OAuth discovery above: the proxy is constructed after the catalog.
+  toolManualService.setHiddenTools(mcpService.hiddenTools);
   // MCP OAuth 2.1 authorization server (our own AS): lets MCP clients with no
   // pre-shared connection key connect via the standard 401 → discovery → DCR →
   // authorize (PKCE) flow. The authorize step routes the browser to /connect
@@ -1225,6 +1360,8 @@ export async function createCoreServices(
     stateSecret: config.jwtSecret,
     publicFrontendUrl: config.publicFrontendUrl,
     tokenPrefix: config.mcpOAuthTokenPrefix,
+    // An agent connection's first use tells its owner's open tabs the agent arrived.
+    events: eventBus,
   });
   // RFC 9728 pointer carried on every MCP 401 challenge so OAuth-capable
   // clients discover the AS. Single source of truth for the resource id.
@@ -1261,8 +1398,22 @@ export async function createCoreServices(
     loadActiveGroups,
   });
   const writeAccess = ports.writeAccess ?? alwaysWritable;
-  const toolHandlerFactory = createToolHandlerFactory(resolveToolContext, writeAccess);
+  // The branch every tool call runs on is resolved by the handler, before the
+  // tool: the default read live (a rename in the settings is the next call's
+  // default), the existence asked without cloning anything.
+  const toolHandlerFactory = createToolHandlerFactory(resolveToolContext, writeAccess, {
+    defaultBranch: () => kb.defaultBranch,
+    isMissing: (branch) => workspaceService.isBranchMissing(branch),
+  });
   const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService, authService);
+  const verifyToolToken = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
+  // Every credential kind this server issues — connection keys, internal
+  // tokens and app sessions (bearer or cookie) — so a fetch carrying another
+  // user's identity of ANY kind is refused the link.
+  const agentDownloadFetcher: (req: Request) => Promise<string[]> = createDownloadFetcherIdentifier(
+    { verifyToolToken, verifySession: (token) => authService.verifyToken(token) },
+    readAuthCookie,
+  );
   // Read-only manual endpoints accept the above PLUS a browser JWT, so a
   // logged-in user can browse the catalog with their session. Execution routes
   // keep `toolAuthMiddleware` (no JWT), so a session can read but not invoke.
@@ -1430,6 +1581,8 @@ export async function createCoreServices(
     kbDirName,
     spillStore,
     agentUploadStore,
+    agentDownloadStore,
+    agentDownloadFetcher,
     docExtractService,
     accessControl,
     creatorAccess,
@@ -1440,8 +1593,11 @@ export async function createCoreServices(
     toolManualService,
     pendingToolsService,
     readAgentPreamble: readPreamble,
+    agentGuide,
+    agentGuideSections: agentGuideSectionsReader,
     pluginIndexService,
     pluginProvisionService,
+    starterPackService,
     joinRequestsService,
     pluginJoinRequestJobs,
     pluginLinkIndex,
@@ -1475,6 +1631,8 @@ export async function createCoreServices(
     connectionProbeService,
     externalApiKeyService,
     internalTokenService,
+    embedService,
+    mcpAppService,
     mcpService,
     mcpAuthMiddleware,
     mcpOAuthProvider,

package/src/core/lifecycle.ts

@@ -291,7 +291,7 @@ export interface BootableCore {
   config: { workspacesRoot: string };
   kbDirName: string;
   kbStartupRunner: Pick<KbStartupRunner, 'runAll' | 'retryUntilMaintained'>;
-  workflowService: Pick<WorkflowService, 'closeChangeRequestsWithDeletedBranches'>;
+  workflowService: Pick<WorkflowService, 'closeChangeRequestsWithDeletedBranches' | 'tidyAfterSweep'>;
   pluginJoinRequestJobs: Pick<PluginJoinRequestJobs, 'startSweeping'>;
   /**
    * The startup phase's retry, when the boot survived an unreachable remote
@@ -390,7 +390,11 @@ export async function startCore<C extends BootableCore>(
         crLog.info(`closed ${n} change request${n === 1 ? '' : 's'} with a deleted branch`);
       }
     })
-    .catch((err) => crLog.warn('deleted-branch sweep failed:', { err }));
+    .catch((err) => crLog.warn('deleted-branch sweep failed:', { err }))
+    // Then the tidy-up: open requests that propose nothing are closed, and the
+    // branches merged requests left behind removed (behind its own setting).
+    // Fails safe on a failed fetch, and never throws.
+    .then(() => core.workflowService.tidyAfterSweep());
 
   // Recorded join requests that are still owed, resumed — now, and then on a
   // timer. SEQUENCED AFTER the startup phase for the same reason as the sweep
@@ -437,6 +441,15 @@ export interface CoreStopDeps {
    * Optional: a caller that has not built one passes nothing.
    */
   agentUploadStore?: { stopSweeping(): void; drainSweep(): Promise<void> };
+  /** The agent download store, whose sweep deletes captured bytes nobody fetched — stopped for the same reason. */
+  agentDownloadStore?: { stopSweeping(): void; drainSweep(): Promise<void> };
+  /**
+   * The workflow service, for the tidy-up it runs after each sweep (closing
+   * empty requests, removing leftover branches): detached from whatever
+   * started it, so stopped and awaited here before the pool goes. Optional:
+   * a caller that has not built one passes nothing.
+   */
+  workflowService?: { stopTidying(): void; drainTidy(): Promise<void> };
   /** The startup phase's retry, if the boot left one asking — see {@link BootableCore.startupRetry}. */
   startupRetry?: { stop(): void } | null;
   /** The database — its pool is ended last, once nothing above can still need it. */
@@ -524,10 +537,14 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // synchronous, and it only clears an interval and tells a sweep already
   // running to stop deleting.
   deps.agentUploadStore?.stopSweeping();
+  deps.agentDownloadStore?.stopSweeping();
   // A startup phase still asking for an unreachable remote stops asking:
   // synchronous, and nothing after it must be able to clone into a
   // workspaces folder that is about to belong to nobody.
   deps.startupRetry?.stop();
+  // The post-sweep tidy-up: no new round, and the one under way stops at its
+  // next request or branch. Synchronous.
+  deps.workflowService?.stopTidying();
   // Clearing the interval stops future ticks; it does nothing to a job a
   // tick already started, which holds a claim it heartbeats through the
   // pool and is mid-clone or mid-push. Awaited here, in the budget: a job
@@ -543,6 +560,15 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.agentUploadStore) {
     await bounded(deps.agentUploadStore.drainSweep(), remaining(), 'finishing the upload sweep', log);
   }
+  if (deps.agentDownloadStore) {
+    await bounded(deps.agentDownloadStore.drainSweep(), remaining(), 'finishing the download sweep', log);
+  }
+  // The tidy-up in flight fetches and deletes branches through the pool and
+  // the default branch's checkout: awaited, so the next graph for this
+  // tenant cannot find a branch deletion still running under it.
+  if (deps.workflowService) {
+    await bounded(deps.workflowService.drainTidy(), remaining(), 'finishing the branch tidy-up', log);
+  }
   await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
   if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);
   await bounded(closeDb(deps.db), remaining(), 'ending the database pool', log);

package/src/core-config.ts

@@ -1,7 +1,7 @@
 import dotenv from 'dotenv';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { defaultKbTemplateDir } from './assets.js';
+import { defaultKbTemplateDir, defaultStarterPacksDir } from './assets.js';
 import { assertKeyDecodesTo32Bytes } from './shared/token-crypto.js';
 import { DEFAULT_GIT_TIMEOUT_MS } from './modules/workflow/git/node-git-runner.js';
 import { DEFAULT_DB_SCHEMA, assertSchemaName } from './modules/database/connection.js';
@@ -103,11 +103,13 @@ export interface TenantConfig {
   readonly gitUsername: string;
   readonly gitToken: string;
   readonly kbTemplateDir: string;
+  readonly starterPacksDir: string;
   readonly updateCheckEnabled: boolean;
   readonly loginPasswordEnabled: boolean;
   readonly allowedEmailDomains: string[];
   readonly secretsEncKey: string;
   readonly internalTokenSecret: string;
+  readonly embedSharedSecret: string;
   readonly trustProxy: string;
   readonly gitTimeoutMs: number;
   readonly publicBackendUrl: string;
@@ -276,6 +278,14 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * existing one. Override with `KB_TEMPLATE_DIR`.
    */
   readonly kbTemplateDir: string;
+  /**
+   * Filesystem path to the starter packs a new knowledge base's admin may
+   * pick from (the `starter-packs/` folder shipped inside this package — see
+   * `defaultStarterPacksDir()`): one folder per team, each a `pack.yaml` with
+   * the pages and the plugin it adds. A distribution offers its own with
+   * `STARTER_PACKS_DIR`; a folder holding no valid pack offers none.
+   */
+  readonly starterPacksDir: string;
   /**
    * In-app update check. When true (default), `GET /api/update-check` lazily
    * asks api.github.com for the newest Hexis release — only when an admin's
@@ -337,6 +347,17 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * independently of user sessions.
    */
   readonly internalTokenSecret: string;
+  /**
+   * The shared secret the Atlassian connector presents to \`POST
+   * /api/embed/token\` (\`EMBED_SHARED_SECRET\`). Unset on a deployment that
+   * has no connector pointed at it, which 404s that one route — the embed
+   * surface itself needs no secret, because the MCP App mints through the
+   * authenticated MCP session instead.
+   *
+   * There is deliberately NO framing setting beside it: any site may frame
+   * the embed page (see the embed module), so there is no allowlist to keep.
+   */
+  readonly embedSharedSecret: string;
   /**
    * Express `trust proxy` setting, from `TRUST_PROXY`: the number of reverse
    * proxy hops in front of this backend (e.g. `1`), or an address/CIDR list
@@ -477,6 +498,7 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     // Default: the `kb-template/` folder shipped inside this package (works
     // both from src/ and compiled dist/ — see assets.ts).
     this.kbTemplateDir = process.env.KB_TEMPLATE_DIR || defaultKbTemplateDir();
+    this.starterPacksDir = process.env.STARTER_PACKS_DIR || defaultStarterPacksDir();
     this.updateCheckEnabled =
       (process.env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false';
     this.allowedEmailDomains = (process.env.ALLOWED_EMAIL_DOMAINS || '')
@@ -503,6 +525,7 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     // key never gets past this line.
     assertKeyDecodesTo32Bytes(this.secretsEncKey, secretsKeySource);
     this.internalTokenSecret = (process.env.INTERNAL_TOKEN_SECRET || '').trim();
+    this.embedSharedSecret = (process.env.EMBED_SHARED_SECRET || '').trim();
     // Setting DOMAIN declares "the bundled Caddy `https` profile fronts this
     // deployment" — one proxy hop, and the public origin IS that domain. The
     // three values below therefore default from it, so `DOMAIN=x.example.com`

package/src/index.ts

@@ -47,8 +47,8 @@ export {
   type LeasedWorker,
 } from './core/lifecycle.js';
 
-// Packaged assets (migrations/, kb-template/) + the migration runners.
-export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
+// Packaged assets (migrations/, kb-template/, agent-guide/, starter-packs/) + the migration runners.
+export { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir, defaultStarterPacksDir } from './assets.js';
 export {
   runCoreMigrations,
   runEnterpriseMigrations,

package/src/modules/access/__tests__/access-control.atref-batch.test.ts

@@ -25,6 +25,8 @@ describe('AccessControlService — at-ref batch reads (git cat-file --batch)', (
   let svc: AccessControlService;
   const workspaceId = 'ws-atref-1';
   const admin = 'razvan@bevel.software';
+  /** In no role and named nowhere — read is default-deny for them. */
+  const stranger = 'mia@bevel.software';
 
   async function git(...args: string[]): Promise<void> {
     await execFileAsync('git', ['-C', repo, ...args]);
@@ -44,6 +46,10 @@ describe('AccessControlService — at-ref batch reads (git cat-file --batch)', (
       '---\nwrite:\n  - deny razvan <razvan@bevel.software>\n---\n# denied\n',
     );
     await fs.writeFile(path.join(repo, 'Knowledge/with space.md'), '# spaced\n');
+    // For the read batch: a folder the whole organisation may open.
+    await fs.mkdir(path.join(repo, 'Knowledge/shared'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Knowledge/shared/access.md'), '---\nread:\n  - everyone\n---\n');
+    await fs.writeFile(path.join(repo, 'Knowledge/shared/note.md'), '# shared\n');
 
     await execFileAsync('git', ['init', '-b', 'main', repo]);
     await git('config', 'user.email', 'test@example.com');
@@ -96,4 +102,56 @@ describe('AccessControlService — at-ref batch reads (git cat-file --batch)', (
     expect(map!.get('Knowledge/denied.md')!.emails.has(admin)).toBe(false);
     expect(map!.get('Knowledge/plain.md')!.emails.has(admin)).toBe(true);
   });
+
+  /**
+   * The read side of the same batch, used by the change-request read tools to
+   * decide which of a request's files their caller may see. The verdicts must
+   * be identical to the single-path `canReadAtRef` the app's own content routes
+   * gate on — a batch that answered even one path differently would show an
+   * agent a file the app refuses to open.
+   */
+  it('canReadBatchAtRef answers default-deny, an `everyone` grant, and write-implies-read in one pass', async () => {
+    const paths = [
+      'Knowledge/plain.md',
+      'Knowledge/shared/note.md',
+      'Knowledge/with space.md',
+      'Knowledge/not-there.md',
+    ];
+    const forStranger = await svc.canReadBatchAtRef(workspaceId, 'main', stranger, paths);
+    expect(forStranger).not.toBeNull();
+    // Nothing names them, so read is refused — except where the folder says everyone.
+    expect(forStranger!.get('Knowledge/plain.md')).toBe(false);
+    expect(forStranger!.get('Knowledge/shared/note.md')).toBe(true);
+    expect(forStranger!.get('Knowledge/with space.md')).toBe(false);
+    expect(forStranger!.get('Knowledge/not-there.md')).toBe(false);
+
+    // The Admin write grant folds into read.
+    const forAdmin = await svc.canReadBatchAtRef(workspaceId, 'main', admin, paths);
+    expect([...forAdmin!.values()]).toEqual([true, true, true, true]);
+  });
+
+  it('canReadBatchAtRef matches the single-path read verdict on every path', async () => {
+    const paths = [
+      'Knowledge/plain.md',
+      'Knowledge/shared/note.md',
+      'Knowledge/with space.md',
+      'Knowledge/not-there.md',
+    ];
+    for (const who of [admin, stranger]) {
+      const batch = await svc.canReadBatchAtRef(workspaceId, 'main', who, paths);
+      for (const path of paths) {
+        const single = await svc.canReadAtRef(workspaceId, 'main', who, path);
+        expect(batch!.get(path), `${who} on ${path}`).toBe(single);
+      }
+    }
+  });
+
+  it('canReadBatchAtRef answers an empty map for no paths, and null for a ref it cannot resolve', async () => {
+    expect(await svc.canReadBatchAtRef(workspaceId, 'main', admin, [])).toEqual(new Map());
+    expect(await svc.canReadBatchAtRef(workspaceId, 'no-such-ref', admin, ['Knowledge/plain.md'])).toBeNull();
+    // The null-semantics hold for the empty set too: the ref is validated
+    // whatever was asked about, so no caller can read an empty map as proof
+    // that the ref resolved.
+    expect(await svc.canReadBatchAtRef(workspaceId, 'no-such-ref', admin, [])).toBeNull();
+  });
 });

package/src/modules/access/__tests__/access-control.platform-restore.test.ts

@@ -67,9 +67,10 @@ describe('restoring a platform file', () => {
     // only because it is the file that says who the admin is — the repository
     // that lost that one too is the last case in this file.
     const svc = service();
-    for (const name of ['.bevelignore', 'AGENTS.md']) {
-      expect(await svc.canRestorePlatformFile(WS, ADMIN, name)).toBe(true);
-    }
+    expect(await svc.canRestorePlatformFile(WS, ADMIN, '.bevelignore')).toBe(true);
+    // The agent guide is not a platform file: it is served from code, never
+    // written to the root, so a root `AGENTS.md` is content and no restore.
+    expect(await svc.canRestorePlatformFile(WS, ADMIN, 'AGENTS.md')).toBe(false);
     // Nothing is missing at `roles.yaml`: the root has one. A move is a rename
     // on disk, so landing another there would REPLACE the admin model rather
     // than put it back, and no exception carries that.
@@ -95,9 +96,9 @@ describe('restoring a platform file', () => {
     expect(await svc.canRestorePlatformFile(WS, ENGINEER, 'Sales/Legal/access.md')).toBe(false);
   });
 
-  it('the three root-only names are a restore at the root and nowhere else', async () => {
+  it('the root-only names are a restore at the root and nowhere else', async () => {
     const svc = service();
-    for (const dest of ['Sales/roles.yaml', 'Sales/.bevelignore', 'Sales/AGENTS.md']) {
+    for (const dest of ['Sales/roles.yaml', 'Sales/.bevelignore']) {
       expect(await svc.canRestorePlatformFile(WS, ADMIN, dest)).toBe(false);
     }
   });
@@ -113,14 +114,14 @@ describe('restoring a platform file', () => {
 
   it('a non-admin never gets the exception, wherever it would land', async () => {
     const svc = service();
-    for (const dest of ['roles.yaml', '.bevelignore', 'AGENTS.md', 'access.md', 'Legal/access.md']) {
+    for (const dest of ['roles.yaml', '.bevelignore', 'access.md', 'Legal/access.md']) {
       expect(await svc.canRestorePlatformFile(WS, ENGINEER, dest)).toBe(false);
     }
   });
 
   it('the deployment owner is an admin for it, and an ordinary destination is not a restore for anyone', async () => {
     const svc = service();
-    expect(await svc.canRestorePlatformFile(WS, OWNER, 'AGENTS.md')).toBe(true);
+    expect(await svc.canRestorePlatformFile(WS, OWNER, '.bevelignore')).toBe(true);
     for (const email of [ADMIN, OWNER]) {
       expect(await svc.canRestorePlatformFile(WS, email, 'Sales/deal.md')).toBe(false);
       expect(await svc.canRestorePlatformFile(WS, email, 'Sales/notes.md')).toBe(false);

package/src/modules/access/__tests__/access-control.service.test.ts

@@ -216,6 +216,25 @@ describe('AccessControlService', () => {
     expect(await svc.canWrite(workspaceId, 'ali@bevel.software', 'Knowledge/Secret/Foo.md')).toBe(false);
   });
 
+  // What deleting a nested access.md (delete_file, or the app's delete) does:
+  // the folder falls back to its parent's rules, nothing else to undo.
+  it('once a nested access.md is deleted, its folder follows the parent\'s rules', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    await writeFile(repo, 'roles.yaml', ROLES_YAML);
+    await writeFile(repo, 'access.md', '---\nread:\n  - everyone\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Team/access.md', '---\nread:\n  - deny Felix Kissel <felix@example.com>\n---\n');
+    await writeFile(repo, 'Team/plan.md', 'plan');
+
+    const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR, new NodeFs());
+    expect(await svc.canRead(workspaceId, 'felix@example.com', 'Team/plan.md')).toBe(false);
+
+    await fs.rm(path.join(repo, 'Team/access.md'));
+    svc.invalidate(workspaceId);
+
+    expect(await svc.canRead(workspaceId, 'felix@example.com', 'Team/plan.md')).toBe(true);
+    expect(await svc.canWrite(workspaceId, 'felix@example.com', 'Team/plan.md')).toBe(false);
+  });
+
   it('closeness beats tier: a closer everyone grant overrides a farther email deny', async () => {
     const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
     await writeFile(repo, 'roles.yaml', ROLES_YAML);