@junejs/server 1.0.0-dev.17 → 1.0.0-dev.20

package/dist/manifest.js

@@ -0,0 +1,111 @@
+import { findMiddlewareFile } from "./router.js";
+import { resolveBoundary } from "./segment.js";
+import { freezeConfig } from "./config-freeze.js";
+import { scanAppRoutes } from "./route-scan.js";
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { routeFromModule } from "@junejs/core/route";
+//#region src/manifest.ts
+async function importLayout(file) {
+	const mod = await import(pathToFileURL(file).href);
+	return typeof mod.default === "function" ? {
+		component: mod.default,
+		boundary: mod.segmentBoundary === true
+	} : null;
+}
+async function buildManifest(appRoot) {
+	const appDir = join(appRoot, "app");
+	const frozen = await freezeConfig(appRoot);
+	const scanned = await scanAppRoutes(appRoot);
+	const layoutCache = /* @__PURE__ */ new Map();
+	const loadCached = async (f) => {
+		if (!layoutCache.has(f)) layoutCache.set(f, await importLayout(f));
+		return layoutCache.get(f) ?? null;
+	};
+	const componentsFor = async (files) => {
+		const items = [];
+		for (const f of files) {
+			const c = await loadCached(f);
+			items.push({
+				file: f,
+				entry: c?.component ?? null,
+				boundary: !!c?.boundary
+			});
+		}
+		return resolveBoundary(items);
+	};
+	const loadingCache = /* @__PURE__ */ new Map();
+	const loadingFor = async (file) => {
+		if (!file) return void 0;
+		if (!loadingCache.has(file)) {
+			const loaded = await importLayout(file);
+			loadingCache.set(file, loaded ? loaded.component : null);
+		}
+		return loadingCache.get(file) ?? void 0;
+	};
+	const routes = {};
+	const dynamicRoutes = [];
+	const resourceRoutes = [];
+	const layoutChains = {};
+	const layoutBoundaries = {};
+	const loadings = {};
+	for (const r of scanned) {
+		const mod = await import(pathToFileURL(r.file).href);
+		if (r.resource) {
+			const handler = mod.default;
+			if (typeof handler === "function") resourceRoutes.push({
+				pattern: r.path,
+				handler
+			});
+			continue;
+		}
+		const def = routeFromModule(mod);
+		if (!def) continue;
+		const { chain, boundaryIndex, key } = await componentsFor(r.layouts);
+		const loading = await loadingFor(r.loading);
+		if (r.dynamic) {
+			dynamicRoutes.push({
+				pattern: r.path,
+				def
+			});
+			layoutChains[r.path] = chain;
+		} else {
+			routes[r.path] = def;
+			layoutChains[r.path] = chain;
+		}
+		if (boundaryIndex !== null && key !== null) layoutBoundaries[r.path] = {
+			index: boundaryIndex,
+			key
+		};
+		if (loading) loadings[r.path] = loading;
+	}
+	let extra;
+	const extraFile = findMiddlewareFile(appDir);
+	if (extraFile) {
+		const mod = await import(pathToFileURL(extraFile).href);
+		if (typeof mod.default === "function") extra = mod.default;
+	}
+	let agentName;
+	const agentDir = join(appDir, frozen.agent.runtime.dir);
+	if (frozen.agent.runtime.enabled && existsSync(agentDir)) {
+		const cfgFile = join(agentDir, "agent.ts");
+		agentName = (existsSync(cfgFile) ? (await import(pathToFileURL(cfgFile).href)).default : void 0)?.name ?? basename(agentDir);
+	}
+	return {
+		routes,
+		dynamicRoutes,
+		resourceRoutes,
+		layoutChains,
+		layoutBoundaries,
+		loadings,
+		document: frozen.document,
+		agent: frozen.agent,
+		agentName,
+		i18n: frozen.i18n,
+		earlyHints: frozen.earlyHints,
+		extra
+	};
+}
+//#endregion
+export { buildManifest, importLayout };

package/dist/route-scan-DMlwoESy.d.ts

@@ -0,0 +1,13 @@
+//#region src/route-scan.d.ts
+type RouteEntry = {
+  path: string;
+  file: string;
+  dynamic: boolean;
+  resource?: boolean;
+  layouts: string[];
+  loading?: string;
+};
+declare function scanRoutes(appDir: string, dir?: string, layouts?: string[], out?: RouteEntry[], loading?: string): Promise<RouteEntry[]>;
+declare function scanAppRoutes(appRoot: string): Promise<RouteEntry[]>;
+//#endregion
+export { scanAppRoutes as n, scanRoutes as r, RouteEntry as t };

package/dist/route-scan.d.ts

@@ -0,0 +1,2 @@
+import { n as scanAppRoutes, r as scanRoutes, t as RouteEntry } from "./route-scan-DMlwoESy.js";
+export { RouteEntry, scanAppRoutes, scanRoutes };

package/dist/route-scan.js

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+//#region src/route-scan.ts
+const PAGE_BASENAMES = /* @__PURE__ */ new Set(["page", "index"]);
+const ROUTE_EXTS = [
+	".tsx",
+	".jsx",
+	".ts",
+	".js"
+];
+const isRouteGroup = (name) => /^\(.+\)$/.test(name);
+function segmentFile(dir, base) {
+	return ROUTE_EXTS.map((e) => join(dir, `${base}${e}`)).find(existsSync);
+}
+async function scanRoutes(appDir, dir = appDir, layouts = [], out = [], loading) {
+	const ownLayout = segmentFile(dir, "layout");
+	const chain = ownLayout ? [...layouts, ownLayout] : layouts;
+	const nearestLoading = segmentFile(dir, "loading") ?? loading;
+	const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+	for (const e of entries) {
+		if (e.name.startsWith("_") || e.name.startsWith(".")) continue;
+		const full = join(dir, e.name);
+		if (e.isDirectory()) {
+			await scanRoutes(appDir, full, chain, out, nearestLoading);
+			continue;
+		}
+		const ext = e.name.match(/\.[^.]+$/)?.[0] ?? "";
+		if (!ROUTE_EXTS.includes(ext)) continue;
+		const base = basename(e.name, ext);
+		const resource = base === "route";
+		if (!PAGE_BASENAMES.has(base) && !resource) continue;
+		const relDir = relative(appDir, dir);
+		const path = "/" + (relDir === "" ? [] : relDir.split(sep).filter((s) => !isRouteGroup(s))).join("/");
+		out.push({
+			path: path === "/" ? "/" : path,
+			file: full,
+			dynamic: /\[.+\]/.test(path),
+			resource,
+			layouts: chain,
+			loading: nearestLoading
+		});
+	}
+	return out;
+}
+async function scanAppRoutes(appRoot) {
+	const appDir = join(appRoot, "app");
+	const juneRoutesDir = join(appRoot, ".june", "routes");
+	const appRoutes = await scanRoutes(appDir);
+	const frameworkRoutes = existsSync(juneRoutesDir) ? await scanRoutes(juneRoutesDir) : [];
+	const appPaths = new Set(appRoutes.map((r) => r.path));
+	return [...appRoutes, ...frameworkRoutes.filter((r) => !appPaths.has(r.path))].sort((a, b) => a.path.localeCompare(b.path));
+}
+//#endregion
+export { scanAppRoutes, scanRoutes };

package/dist/worker-BkFHGtxp.d.ts

@@ -0,0 +1,61 @@
+import { l as ResourceHandler, n as LayoutComponent, r as LoadingComponent, t as ExtraHandler } from "./pipeline-cCR6MGNK.js";
+import { Channel, ChannelFactory } from "@junejs/core/agent-config";
+import { BrandedRoute } from "@junejs/core/route";
+import { AgentConfig } from "@junejs/core/config";
+import React from "react";
+import { DocumentConfig } from "@junejs/core/document";
+import { I18nConfig } from "@junejs/core/i18n";
+import { Resources } from "@junejs/core/resources";
+//#region src/worker.d.ts
+type WorkerExecutionContext = {
+  waitUntil?(p: Promise<unknown>): void;
+};
+type WorkerManifest = {
+  routes: Record<string, BrandedRoute>;
+  dynamicRoutes?: Array<{
+    pattern: string;
+    def: BrandedRoute;
+  }>;
+  resourceRoutes?: Array<{
+    pattern: string;
+    handler: ResourceHandler;
+  }>;
+  layoutChains?: Record<string, LayoutComponent[]>;
+  layoutBoundaries?: Record<string, {
+    index: number;
+    key: string;
+  }>;
+  loadings?: Record<string, LoadingComponent>;
+  document: DocumentConfig;
+  agent: AgentConfig;
+  agentName?: string;
+  agentChannels?: (Channel | ChannelFactory)[];
+  i18n?: I18nConfig;
+  earlyHints?: string[];
+  htmlCacheControl?: string;
+  notFound?: React.ComponentType<{
+    pathname: string;
+  }>;
+  extra?: ExtraHandler;
+  resources?: (env?: unknown) => Promise<Resources> | Resources;
+  services?: (env?: unknown) => unknown;
+};
+declare function createWorker(manifest: WorkerManifest): {
+  fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response>;
+};
+type AssetEnv = {
+  ASSETS?: {
+    fetch(request: Request): Promise<Response>;
+  };
+};
+type FetchPipeline = {
+  fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response>;
+};
+declare function withAssets(pipeline: FetchPipeline, opts?: {
+  link?: string | null;
+}): {
+  fetch(request: Request, env?: AssetEnv, ctx?: WorkerExecutionContext): Promise<Response>;
+};
+declare function withDenoAssets(pipeline: FetchPipeline): (request: Request) => Promise<Response>;
+//#endregion
+export { withDenoAssets as a, withAssets as i, WorkerManifest as n, createWorker as r, WorkerExecutionContext as t };

package/dist/worker.d.ts

@@ -1,56 +1,2 @@
-import { l as ResourceHandler, n as LayoutComponent, r as LoadingComponent, t as ExtraHandler } from "./pipeline-cCR6MGNK.js";
-import { BrandedRoute } from "@junejs/core/route";
-import { AgentConfig } from "@junejs/core/config";
-import React from "react";
-import { DocumentConfig } from "@junejs/core/document";
-import { I18nConfig } from "@junejs/core/i18n";
-import { Resources } from "@junejs/core/resources";
-//#region src/worker.d.ts
-type WorkerManifest = {
-  routes: Record<string, BrandedRoute>;
-  dynamicRoutes?: Array<{
-    pattern: string;
-    def: BrandedRoute;
-  }>;
-  resourceRoutes?: Array<{
-    pattern: string;
-    handler: ResourceHandler;
-  }>;
-  layoutChains?: Record<string, LayoutComponent[]>;
-  layoutBoundaries?: Record<string, {
-    index: number;
-    key: string;
-  }>;
-  loadings?: Record<string, LoadingComponent>;
-  document: DocumentConfig;
-  agent: AgentConfig;
-  agentName?: string;
-  i18n?: I18nConfig;
-  earlyHints?: string[];
-  htmlCacheControl?: string;
-  notFound?: React.ComponentType<{
-    pathname: string;
-  }>;
-  extra?: ExtraHandler;
-  resources?: (env?: unknown) => Promise<Resources> | Resources;
-  services?: (env?: unknown) => unknown;
-};
-declare function createWorker(manifest: WorkerManifest): {
-  fetch(request: Request, env?: unknown): Promise<Response>;
-};
-type AssetEnv = {
-  ASSETS?: {
-    fetch(request: Request): Promise<Response>;
-  };
-};
-type FetchPipeline = {
-  fetch(request: Request, env?: unknown): Promise<Response>;
-};
-declare function withAssets(pipeline: FetchPipeline, opts?: {
-  link?: string | null;
-}): {
-  fetch(request: Request, env?: AssetEnv): Promise<Response>;
-};
-declare function withDenoAssets(pipeline: FetchPipeline): (request: Request) => Promise<Response>;
-//#endregion
-export { WorkerManifest, createWorker, withAssets, withDenoAssets };
+import { a as withDenoAssets, i as withAssets, n as WorkerManifest, r as createWorker, t as WorkerExecutionContext } from "./worker-BkFHGtxp.js";
+export { WorkerExecutionContext, WorkerManifest, createWorker, withAssets, withDenoAssets };

package/dist/worker.js

@@ -1,4 +1,4 @@
-import { durableAgentSurface } from "./agent-durable.js";
+import { durableAgentSurface, durableChannelSurface } from "./agent-durable.js";
 import { createPipeline } from "./pipeline.js";
 import { RESERVED_PREFIX, contentTypeFor, safeRelativePath } from "./static-files.js";
 //#region src/worker.ts
@@ -61,15 +61,30 @@ function createWorker(manifest) {
 	const loadingFor = (key) => manifest.loadings?.[key];
 	const boundaryFor = (key) => manifest.layoutBoundaries?.[key] ?? null;
 	let currentEnv;
+	const requestLocals = /* @__PURE__ */ new WeakMap();
 	const provider = manifest.resources;
 	const servicesProvider = manifest.services;
 	let servicesCache;
 	const agentSurface = manifest.agent.runtime.enabled && manifest.agentName ? (() => {
-		const route = durableAgentSurface(() => currentEnv?.AGENT, {
-			agentName: manifest.agentName,
-			chatPath: manifest.agent.runtime.chat.path
-		});
-		return (req) => route(req);
+		const agentName = manifest.agentName;
+		const wantChannels = manifest.agent.runtime.channels !== false && (manifest.agentChannels?.length ?? 0) > 0;
+		return async (req) => {
+			const locals = requestLocals.get(req);
+			const ns = () => (locals?.env)?.AGENT;
+			const chatRes = await durableAgentSurface(ns, {
+				agentName,
+				chatPath: manifest.agent.runtime.chat.path
+			})(req);
+			if (chatRes) return chatRes;
+			if (!wantChannels) return null;
+			return durableChannelSurface(ns, {
+				agentName,
+				channels: manifest.agentChannels,
+				env: locals?.env,
+				services: servicesProvider,
+				waitUntil: locals?.ctx?.waitUntil?.bind(locals.ctx)
+			})(req);
+		};
 	})() : void 0;
 	const pipeline = createPipeline({
 		docConfig: manifest.document,
@@ -130,14 +145,18 @@ function createWorker(manifest) {
 			return null;
 		}
 	});
-	return { fetch(request, env) {
+	return { fetch(request, env, ctx) {
 		currentEnv = env;
+		requestLocals.set(request, {
+			env,
+			ctx
+		});
 		return pipeline.fetch(request);
 	} };
 }
 const estimateTokens = (s) => String(Math.ceil(s.length / 4));
 function withAssets(pipeline, opts = {}) {
-	return { async fetch(request, env) {
+	return { async fetch(request, env, ctx) {
 		const assets = env?.ASSETS;
 		const url = new URL(request.url);
 		const isPagePath = !/\.[a-z0-9]+$/i.test(url.pathname);
@@ -177,7 +196,7 @@ function withAssets(pipeline, opts = {}) {
 				return a;
 			}
 		}
-		return pipeline.fetch(request, env);
+		return pipeline.fetch(request, env, ctx);
 	} };
 }
 function withDenoAssets(pipeline) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "1.0.0-dev.17",
+  "version": "1.0.0-dev.20",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -138,7 +138,7 @@
     "rolldown": "^1.1.0"
   },
   "peerDependencies": {
-    "@junejs/core": ">=0.2.0-dev.33",
+    "@junejs/core": ">=0.2.0-dev.38",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-server-dom-webpack": "19.2.7",

package/src/agent-compile.ts

@@ -31,6 +31,8 @@ export type AgentDirScan = {
   name: string;
   hasConfig: boolean;
   instructions: string | null;
+  // instructions.<source>.md at the agent root — per-surface variants (#149).
+  surfaceVariants: { source: string; raw: string }[];
   tools: string[]; // relative specifiers, e.g. "./tools/create_order.ts"
   skills: { name: string; raw: string }[];
   channels: string[]; // "./channels/slack.ts"
@@ -59,6 +61,12 @@ export function scanAgentDir(dir: string): AgentDirScan | null {
     name: basename(dir),
     hasConfig: existsSync(join(dir, "agent.ts")),
     instructions: existsSync(instructionsFile) ? readFileSync(instructionsFile, "utf8") : null,
+    surfaceVariants: readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile())
+      .map((e) => e.name.match(/^instructions\.([a-z0-9_-]+)\.md$/))
+      .filter((m): m is RegExpMatchArray => m !== null)
+      .sort((a, b) => a[1]!.localeCompare(b[1]!))
+      .map((m) => ({ source: m[1]!, raw: readFileSync(join(dir, m[0]!), "utf8") })),
     tools: list(join(dir, "tools"), ".ts").map((f) => `./tools/${f}`),
     skills: list(join(dir, "skills"), ".md").map((f) => ({
       name: basename(f, ".md"),
@@ -77,6 +85,7 @@ export function scanAgentDir(dir: string): AgentDirScan | null {
     !scan.tools.length &&
     !scan.skills.length &&
     !scan.channels.length &&
+    !scan.surfaceVariants.length &&
     !scan.channelOverlays.length &&
     !scan.connections.length;
   return empty ? null : scan;
@@ -139,6 +148,9 @@ export function emitAgentModule(scan: AgentDirScan, opts?: EmitOptions): string
     "export const agentModule: AgentModule = {",
     "  config,",
     `  instructions: ${JSON.stringify(scan.instructions ?? "")},`,
+    scan.surfaceVariants.length
+      ? `  surfaceInstructions: {\n${scan.surfaceVariants.map((v) => `    ${JSON.stringify(v.source)}: ${JSON.stringify(v.raw)},`).join("\n")}\n  },`
+      : "  surfaceInstructions: {},",
     `  tools: [${toolIds.join(", ")}],`,
     scan.skills.length
       ? `  skills: [\n${scan.skills.map((s) => `    parseSkill(${JSON.stringify(s.name)}, ${JSON.stringify(s.raw)}),`).join("\n")}\n  ],`
@@ -235,6 +247,20 @@ export function generateAgentModule(
 ): { file: string; code: string; stale: boolean; written: boolean } | null {
   const scan = scanAgentDir(dir);
   if (!scan) return null;
+  for (const o of scan.channelOverlays) {
+    console.warn(
+      `[june] deprecated: channels/${o.source}.md — move it to instructions.${o.source}.md at the agent root (per-surface behavior is agent-level; see junebuild/june#149).`,
+    );
+  }
+  // A variant-shaped file the grammar doesn't parse yet must never be silently
+  // inert (the same failure class this whole convention exists to kill).
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.isFile() && /^instructions\..+\.md$/.test(e.name) && !/^instructions\.[a-z0-9_-]+\.md$/.test(e.name)) {
+      console.warn(
+        `[june] ${e.name}: unrecognized instructions variant — only single-segment sources (instructions.<source>.md) are parsed today; locale variants are a planned follow-up (junebuild/june#149). This file is ignored.`,
+      );
+    }
+  }
   const code = emitAgentModule(scan, { tsExtensions: opts?.tsExtensions ?? sniffTsExtensions(dir) });
   const file = join(dir, AGENT_MODULE_FILE);
   const existing = existsSync(file) ? readFileSync(file, "utf8") : null;

package/src/agent-discover.ts

@@ -3,13 +3,16 @@
 // An agent is a DIRECTORY, not a config object. Location determines function:
 //
 //   agent/
-//     agent.ts         → default-exports a plain config { name, model?, description? }
-//     instructions.md  → system prompt
-//     tools/*.ts       → each default-exports a defineAction (a tool)
-//     skills/*.md      → each a procedure, loaded on demand (progressive disclosure)
-//     channels/*.ts    → each default-exports a Channel (an inbound edge)
-//     channels/*.md    → source-keyed system overlay for the same-named channel
-//     connections/*.ts → each default-exports a Connection (an outbound tool source)
+//     agent.ts                  → default-exports a plain config { name, model?, surfaces? }
+//     instructions.md           → base system prompt
+//     instructions.<source>.md  → per-surface instruction variant (#149)
+//     tools/*.ts                → each default-exports a defineAction (a tool),
+//                                 OR an array of defineActions (an integration
+//                                 shipping several tools, e.g. googleDriveTools())
+//     skills/*.md               → each a procedure, loaded on demand (progressive disclosure)
+//     channels/*.ts             → each default-exports a Channel (an inbound edge — pure transport)
+//     channels/*.md             → DEPRECATED overlay location (warned; use instructions.<source>.md)
+//     connections/*.ts          → each default-exports a Connection (an outbound tool source)
 //
 // There is no central registry to keep in sync — the directory IS the manifest.
 // Because tools are `defineAction`s, the SAME directory is also an MCP server and
@@ -23,8 +26,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
-import type { AnyAction } from "@junejs/core/agent";
-import { assembleAgent, parseSkill, type AgentConfigFile, type AgentDefinition, type AgentModule, type Channel, type ChannelFactory, type Skill } from "@junejs/core/agent-config";
+import { assembleAgent, parseSkill, type AgentConfigFile, type AgentDefinition, type AgentModule, type Channel, type ChannelFactory, type Skill, type ToolEntry } from "@junejs/core/agent-config";
 import type { Connection } from "@junejs/core/connections";
 
 // `_`-prefixed files are private by convention (mirrors the app/ router) — most
@@ -51,10 +53,32 @@ export async function discoverAgentModule(dir: string): Promise<AgentModule> {
   const instructionsFile = join(dir, "instructions.md");
   const instructions = existsSync(instructionsFile) ? await readFile(instructionsFile, "utf8") : "";
 
-  const tools: AnyAction[] = [];
+  // instructions.<source>.md — the agent's per-surface instruction variants
+  // (#149): applied to turns arriving through that source, composed per
+  // config.surfaces (append by default, "replace" to stand alone).
+  const surfaceInstructions: Record<string, string> = {};
+  if (existsSync(dir)) {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+      if (!e.isFile() || !/^instructions\..+\.md$/.test(e.name)) continue;
+      const m = e.name.match(/^instructions\.([a-z0-9_-]+)\.md$/);
+      if (m) {
+        surfaceInstructions[m[1]!] = await readFile(join(dir, e.name), "utf8");
+      } else {
+        // A variant-shaped file the grammar doesn't parse yet (e.g. a locale
+        // suffix, instructions.slack.zh-TW.md) must never be SILENTLY inert.
+        console.warn(
+          `[june] ${e.name}: unrecognized instructions variant — only single-segment sources (instructions.<source>.md) are parsed today; locale variants are a planned follow-up (junebuild/june#149). This file is ignored.`,
+        );
+      }
+    }
+  }
+
+  // A tool file default-exports one tool OR an array of tools (an integration
+  // like googleDriveTools()); assembly flattens arrays.
+  const tools: ToolEntry[] = [];
   for (const f of await scan(join(dir, "tools"), ".ts")) {
     const mod = await import(pathToFileURL(f).href);
-    if (mod.default) tools.push(mod.default as AnyAction);
+    if (mod.default) tools.push(mod.default as ToolEntry);
   }
 
   const skills: Skill[] = [];
@@ -71,11 +95,16 @@ export async function discoverAgentModule(dir: string): Promise<AgentModule> {
     if (mod.default) channels[basename(f, ".ts")] = mod.default as Channel | ChannelFactory;
   }
 
-  // channels/<source>.md — a system overlay applied when a turn's inbound event
-  // source matches the file's basename (see AgentDefinition.channelInstructions).
+  // channels/<source>.md — the DEPRECATED overlay convention (#149): behavior
+  // prose belongs at the agent level (instructions.<source>.md), not beside
+  // transport code. Still honored for one dev-series, loudly.
   const channelInstructions: Record<string, string> = {};
   for (const f of await scan(join(dir, "channels"), ".md")) {
-    channelInstructions[basename(f, ".md")] = await readFile(f, "utf8");
+    const source = basename(f, ".md");
+    console.warn(
+      `[june] deprecated: channels/${source}.md — move it to instructions.${source}.md at the agent root (per-surface behavior is agent-level; see junebuild/june#149).`,
+    );
+    channelInstructions[source] = await readFile(f, "utf8");
   }
 
   // connections/*.ts — outbound: definitions of external MCP/OpenAPI servers;
@@ -86,7 +115,7 @@ export async function discoverAgentModule(dir: string): Promise<AgentModule> {
     if (mod.default) connections.push(mod.default as Connection);
   }
 
-  return { config, instructions, tools, skills, channels, channelInstructions, connections };
+  return { config, instructions, surfaceInstructions, tools, skills, channels, channelInstructions, connections };
 }
 
 // Discover an agent from its directory, returning the assembled AgentDefinition