@junejs/server 1.0.0-dev.28 → 1.0.0-dev.36

package/dist/sqlite-driver.d.ts

@@ -1,6 +1,6 @@
 import { JuneDb } from "@junejs/core/resources";
 //#region src/sqlite-driver.d.ts
-type SyncStatement = {
+export type SyncStatement = {
   all(...params: unknown[]): unknown[];
   get(...params: unknown[]): unknown;
   run(...params: unknown[]): {
@@ -8,18 +8,17 @@ type SyncStatement = {
     lastInsertRowid?: number | bigint;
   };
 };
-type SyncSqlite = {
+export type SyncSqlite = {
   query(sql: string): SyncStatement;
   exec(sql: string): void;
   close(): void;
 };
-declare const NODE_SQLITE_MIN_LTS = "22.13.0";
-declare const NODE_SQLITE_MIN_ODD = "23.4.0";
-declare function nodeSqliteHelp(nodeVersion: string): string;
-declare function isNodeSqliteExperimentalWarning(type: unknown, message: string): boolean;
+export declare const NODE_SQLITE_MIN_LTS = "22.13.0";
+export declare const NODE_SQLITE_MIN_ODD = "23.4.0";
+export declare function nodeSqliteHelp(nodeVersion: string): string;
+export declare function isNodeSqliteExperimentalWarning(type: unknown, message: string): boolean;
 type EmitWarning = (warning: string | Error, ...rest: unknown[]) => void;
-declare function makeWarningFilter(original: EmitWarning): EmitWarning;
-declare function openLocalSqliteSync(path: string): Promise<SyncSqlite>;
-declare function openLocalSqlite(path: string): Promise<JuneDb>;
-//#endregion
-export { NODE_SQLITE_MIN_LTS, NODE_SQLITE_MIN_ODD, SyncSqlite, SyncStatement, isNodeSqliteExperimentalWarning, makeWarningFilter, nodeSqliteHelp, openLocalSqlite, openLocalSqliteSync };
+export declare function makeWarningFilter(original: EmitWarning): EmitWarning;
+export declare function openLocalSqliteSync(path: string): Promise<SyncSqlite>;
+export declare function openLocalSqlite(path: string): Promise<JuneDb>;
+//#endregion

package/dist/static-files.d.ts

@@ -1,6 +1,5 @@
 //#region src/static-files.d.ts
-declare const RESERVED_PREFIX = "_june";
-declare function contentTypeFor(pathname: string): string;
-declare function safeRelativePath(pathname: string): string | null;
-//#endregion
-export { RESERVED_PREFIX, contentTypeFor, safeRelativePath };
+export declare const RESERVED_PREFIX = "_june";
+export declare function contentTypeFor(pathname: string): string;
+export declare function safeRelativePath(pathname: string): string | null;
+//#endregion

package/dist/tsconfig-jsx.d.ts

@@ -1,16 +1,15 @@
 //#region src/tsconfig-jsx.d.ts
-declare const stripJsonc: (s: string) => string;
+export declare const stripJsonc: (s: string) => string;
 /** Read the app's tsconfig.json and return compilerOptions.jsxImportSource.
  *  Follows one level of `extends` so apps that inherit from a base tsconfig
  *  (e.g. "@kurajs/docs/tsconfig.kura.json") are handled correctly.
  *  Returns undefined when absent or unreadable. */
-declare function appJsxImportSource(appRoot: string): Promise<string | undefined>;
+export declare function appJsxImportSource(appRoot: string): Promise<string | undefined>;
 /** The transform.jsx both bundles use: June's island JSX runtime, with the explicit importSource
  *  skipped when the app's tsconfig already declares it — rolldown then reads it from tsconfig
  *  silently instead of warning about the (same-value) override. */
-declare function jsxTransform(appRoot: string): Promise<{
+export declare function jsxTransform(appRoot: string): Promise<{
   runtime: "automatic";
   importSource?: string;
 }>;
-//#endregion
-export { appJsxImportSource, jsxTransform, stripJsonc };
+//#endregion

package/dist/turn-events.d.ts

@@ -1,5 +1,4 @@
 import { AgentSession, TurnEvent } from "@junejs/core/agent-runtime";
 //#region src/turn-events.d.ts
-declare function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable<TurnEvent>;
-//#endregion
-export { observeTurnEvents };
+export declare function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable<TurnEvent>;
+//#endregion

package/dist/web-manifest.d.ts

@@ -1,6 +1,5 @@
 import { DocumentConfig } from "@junejs/core/document";
 //#region src/web-manifest.d.ts
-declare function shortName(site: DocumentConfig["site"]): string | undefined;
-declare function webManifest(config: DocumentConfig): string;
-//#endregion
-export { shortName, webManifest };
+export declare const shortName: (site: DocumentConfig["site"]) => string | undefined;
+export declare function webManifest(config: DocumentConfig): string;
+//#endregion

package/dist/web-manifest.js

@@ -1,11 +1,7 @@
+import { siteShortName } from "@junejs/core/config";
 import { resolveThemeColor } from "@junejs/core/document";
 //#region src/web-manifest.ts
-function shortName(site) {
-	if (site.shortName) return site.shortName;
-	const name = site.name?.trim();
-	if (!name) return void 0;
-	return name.split(/\s+[—–|-]\s+|:\s+/)[0].trim() || name;
-}
+const shortName = (site) => siteShortName(site);
 function webManifest(config) {
 	const base = config.basePath ?? "";
 	const theme = resolveThemeColor(config);

package/dist/{worker-BkFHGtxp.d.ts → worker-Dv4l6Ybs.d.ts}

@@ -1,4 +1,4 @@
-import { l as ResourceHandler, n as LayoutComponent, r as LoadingComponent, t as ExtraHandler } from "./pipeline-cCR6MGNK.js";
+import { l as ResourceHandler, n as LayoutComponent, r as LoadingComponent, t as ExtraHandler } from "./pipeline-BHUjBO0G.js";
 import { Channel, ChannelFactory } from "@junejs/core/agent-config";
 import { BrandedRoute } from "@junejs/core/route";
 import { AgentConfig } from "@junejs/core/config";
@@ -40,7 +40,9 @@ type WorkerManifest = {
   resources?: (env?: unknown) => Promise<Resources> | Resources;
   services?: (env?: unknown) => unknown;
 };
-declare function createWorker(manifest: WorkerManifest): {
+declare function createWorker(manifest: WorkerManifest, opts?: {
+  staticBuild?: boolean;
+}): {
   fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response>;
 };
 type AssetEnv = {

package/dist/worker.d.ts

@@ -1,2 +1,2 @@
-import { a as withDenoAssets, i as withAssets, n as WorkerManifest, r as createWorker, t as WorkerExecutionContext } from "./worker-BkFHGtxp.js";
+import { a as withDenoAssets, i as withAssets, n as WorkerManifest, r as createWorker, t as WorkerExecutionContext } from "./worker-Dv4l6Ybs.js";
 export { WorkerExecutionContext, WorkerManifest, createWorker, withAssets, withDenoAssets };

package/dist/worker.js

@@ -1,4 +1,5 @@
 import { durableAgentSurface, durableChannelSurface } from "./agent-durable.js";
+import { acceptTarget } from "./negotiate.js";
 import { createPipeline } from "./pipeline.js";
 import { RESERVED_PREFIX, contentTypeFor, safeRelativePath } from "./static-files.js";
 //#region src/worker.ts
@@ -45,7 +46,7 @@ function compilePattern(pattern) {
 		names
 	};
 }
-function createWorker(manifest) {
+function createWorker(manifest, opts = {}) {
 	const dynamic = (manifest.dynamicRoutes ?? []).map((d) => ({
 		...compilePattern(d.pattern),
 		def: d.def,
@@ -92,6 +93,7 @@ function createWorker(manifest) {
 		agentSurface,
 		i18n: manifest.i18n,
 		routeList: () => routeList,
+		staticBuild: opts.staticBuild,
 		earlyHints: manifest.earlyHints,
 		htmlCacheControl: manifest.htmlCacheControl,
 		notFoundComponent: manifest.notFound,
@@ -155,28 +157,41 @@ function createWorker(manifest) {
 	} };
 }
 const estimateTokens = (s) => String(Math.ceil(s.length / 4));
+function varyAccept(headers) {
+	const vary = headers.get("vary");
+	if (!vary) headers.set("vary", "accept");
+	else if (vary.trim() !== "*" && !vary.split(",").some((v) => v.trim().toLowerCase() === "accept")) headers.set("vary", `${vary}, accept`);
+}
 function withAssets(pipeline, opts = {}) {
 	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);
-		const accept = request.headers.get("accept") ?? "";
-		if (assets && request.method === "GET" && isPagePath && /text\/markdown/.test(accept)) {
-			const base = url.pathname === "/" ? "/index" : url.pathname.replace(/\/+$/, "");
-			const mdUrl = new URL(url);
-			mdUrl.pathname = `${base}.md`;
-			const a = await assets.fetch(new Request(mdUrl.toString(), { headers: request.headers }));
-			if (a.ok) {
-				const body = await a.text();
-				const headers = new Headers(a.headers);
-				headers.set("content-type", "text/markdown; charset=utf-8");
-				headers.set("x-markdown-tokens", estimateTokens(body));
-				if (opts.link) headers.set("link", opts.link);
-				return new Response(body, {
-					status: 200,
-					headers
-				});
+		const target = isPagePath ? acceptTarget(request.headers.get("accept") ?? "") : null;
+		if (target && (request.method === "GET" || request.method === "HEAD")) {
+			if (assets && request.method === "GET" && (target === "md" || target === "json")) {
+				const base = url.pathname === "/" ? "/index" : url.pathname.replace(/\/+$/, "");
+				const assetUrl = new URL(url);
+				assetUrl.pathname = `${base}.${target}`;
+				const a = await assets.fetch(new Request(assetUrl.toString(), { headers: request.headers }));
+				if (a.ok) {
+					const headers = new Headers(a.headers);
+					if (opts.link) headers.set("link", opts.link);
+					varyAccept(headers);
+					if (target === "json") return new Response(a.body, {
+						status: 200,
+						headers
+					});
+					const body = await a.text();
+					headers.set("content-type", "text/markdown; charset=utf-8");
+					headers.set("x-markdown-tokens", estimateTokens(body));
+					return new Response(body, {
+						status: 200,
+						headers
+					});
+				}
 			}
+			return pipeline.fetch(request, env, ctx);
 		}
 		if (assets && (request.method === "GET" || request.method === "HEAD")) {
 			const a = await assets.fetch(request);
@@ -184,10 +199,12 @@ function withAssets(pipeline, opts = {}) {
 				const ct = a.headers.get("content-type") ?? "";
 				const addLink = !!opts.link && ct.includes("text/html") && !a.headers.has("link");
 				const immutable = /\.[a-f0-9]{8,}\.(css|js)$/.test(url.pathname);
-				if (addLink || immutable) {
+				const negotiated = isPagePath && ct.includes("text/html");
+				if (addLink || immutable || negotiated) {
 					const headers = new Headers(a.headers);
 					if (addLink) headers.set("link", opts.link);
 					if (immutable) headers.set("cache-control", "public, max-age=31536000, immutable");
+					if (negotiated) varyAccept(headers);
 					return new Response(a.body, {
 						status: a.status,
 						headers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "1.0.0-dev.28",
+  "version": "1.0.0-dev.36",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -136,14 +136,14 @@
     "@momiji-rs/sparkdown": "^0.0.4",
     "@resvg/resvg-wasm": "^2.6.2",
     "lightningcss": "^1.27.0",
-    "oxc-parser": "^0.137.0",
+    "oxc-parser": "^0.151.0",
     "rolldown": "^1.1.0"
   },
   "peerDependencies": {
-    "@junejs/core": ">=0.2.0-dev.48",
+    "@junejs/core": ">=0.2.0-dev.57",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "react-server-dom-webpack": "19.2.7",
+    "react-server-dom-webpack": "19.3.0",
     "pg": "^8.0.0",
     "mysql2": "^3.0.0",
     "@libsql/client": "^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0",
@@ -176,6 +176,6 @@
     "@types/pg": "^8.20.0",
     "mysql2": "^3.22.5",
     "pg": "^8.21.0",
-    "react-server-dom-webpack": "19.2.7"
+    "react-server-dom-webpack": "19.3.0"
   }
 }

package/src/agent-durable.ts

@@ -17,8 +17,11 @@
 
 import {
   AgentSession,
+  grantAnswer,
   ResumeAuthorizationError,
   withSystem,
+  type Answerers,
+  type AuthorizeAnswer,
   type ChannelPolicy,
   type EventSink,
   type TurnEvent,
@@ -32,6 +35,7 @@ import {
   type TurnError,
   type TurnFailurePhase,
 } from "@junejs/core/agent-runtime";
+import type { Principal } from "@junejs/core/context";
 import type { Resources } from "@junejs/core/resources";
 import { observeTurnEvents } from "./turn-events";
 import {
@@ -238,6 +242,9 @@ export type DoAgentDef = {
   // emitted mid-turn and ALS propagates), but that is NOT contract — don't rely on
   // ambient db/services; close over what you need.
   onTurnError?: (failure: { turnId: string; error: TurnError; phase?: TurnFailurePhase; step?: string }) => void | Promise<void>;
+  // Decides a { policy } answerer of a parked requestInput at /resume (#261) — the same hook
+  // an AgentDefinition carries natively; assembleDurable passes agent.ts's through.
+  authorizeAnswer?: AuthorizeAnswer;
 };
 
 // The agent runtime INSIDE a Durable Object. A plain class (constructor takes the
@@ -280,6 +287,7 @@ export class AgentDurableObject {
   private connectionsOpened: Promise<void> | undefined;
   private readonly doEnv: unknown;
   private readonly services: unknown;
+  private readonly authorizeAnswer?: AuthorizeAnswer;
   private resolveResources(): Promise<Resources> {
     return (this.resourcesOpened ??= Promise.resolve(
       typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : (this.resourcesInput ?? {}),
@@ -321,6 +329,7 @@ export class AgentDurableObject {
     this.connectionsInput = def.connections;
     this.doEnv = def.env;
     this.services = def.services;
+    this.authorizeAnswer = def.authorizeAnswer;
     const name = def.name ?? "agent";
     // Failure observability (#76): a turn that dies after the fast-ACK has no other
     // observable surface on the edge — the webhook already 200'd and runBackground
@@ -564,8 +573,8 @@ export class AgentDurableObject {
     // VERIFIED identity, so the app must authenticate it upstream (e.g. take the user id from a
     // signature-checked Slack interaction payload), never expose this endpoint raw to clients.
     if (req.method === "POST" && url.pathname.endsWith("/resume")) {
-      const { turnId, inputId, input, by, source, target } = (await req.json()) as {
-        turnId: string; inputId: string; input: unknown; by?: string;
+      const { turnId, inputId, input, by, principal, source, target } = (await req.json()) as {
+        turnId: string; inputId: string; input: unknown; by?: string; principal?: Principal;
         source?: string; target?: ResumeDeliveryTarget;
       };
       await ensureScope();
@@ -595,7 +604,23 @@ export class AgentDurableObject {
       let session: AgentSession;
       try {
         session = this.resolveSession(key);
-        runInScope({ resources, services: this.services }, () => session.resume(turnId, inputId, input, { by }));
+      } catch (err) {
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+      // A { policy } answerer is the app's call (#261), made before the synchronous
+      // resume-then-subscribe section and inside the request scope (the hook may read the db).
+      // The hook is app code: a failure there (a db outage) is a 500 — never the 409 a
+      // resume-state conflict gets, which would tell the caller its answer is stale.
+      let granted: Answerers | undefined;
+      try {
+        granted = await runInScope({ resources, services: this.services }, () =>
+          grantAnswer(session, { turnId, inputId, by, principal }, this.authorizeAnswer));
+      } catch (err) {
+        console.error(`[june] agent "${this.name}": authorizeAnswer failed for input "${inputId}" of turn ${turnId}:`, err);
+        return Response.json({ error: `authorizeAnswer failed: ${err instanceof Error ? err.message : String(err)} — the answer was NOT applied` }, { status: 500 });
+      }
+      try {
+        runInScope({ resources, services: this.services }, () => session.resume(turnId, inputId, input, { by, granted }));
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         // 403: the resumer may not answer; 409: not suspended / wrong turn / wrong input id / key mismatch
@@ -1042,16 +1067,20 @@ export function durableChannelSurface(
 // run the turn, so on a serialization failure we drop it rather than let an
 // unserializable payload take down turn forwarding entirely. (raw is optional on
 // InboundEvent precisely because it may not survive this boundary.)
-// Serialize a /resume RPC body. `input` is `unknown` — the human's answer — so a
-// (third-party) host could hand us something JSON.stringify chokes on (BigInt, circular).
-// Unlike serializeTurn's `raw`, `input` is essential: silently dropping it would resume the
-// turn with the wrong answer. So fail loudly with a clear message rather than corrupt the resume.
-function serializeResume(o: { turnId: string; inputId: string; input: unknown; by?: string; source?: string; target?: ResumeDeliveryTarget }): string {
+// Serialize a /resume RPC body. `input` (the human's answer) and `principal` (the resumer,
+// whose extra fields are `unknown`) come from a (third-party) host and could hold something
+// JSON.stringify chokes on (BigInt, circular). Unlike serializeTurn's `raw`, neither is
+// droppable: resuming without them answers wrongly or as the wrong person. So fail loudly,
+// naming the field that failed, rather than corrupt the resume.
+function serializeResume(o: { turnId: string; inputId: string; input: unknown; by?: string; principal?: Principal; source?: string; target?: ResumeDeliveryTarget }): string {
   try {
-    return JSON.stringify({ turnId: o.turnId, inputId: o.inputId, input: o.input, by: o.by, source: o.source, target: o.target });
+    return JSON.stringify({ turnId: o.turnId, inputId: o.inputId, input: o.input, by: o.by, principal: o.principal, source: o.source, target: o.target });
   } catch (err) {
+    const culprit = (["input", "principal"] as const).find((field) => {
+      try { JSON.stringify(o[field]); return false; } catch { return true; }
+    }) ?? "payload";
     // API-neutral prefix: this serializer backs both resumeStream and resumeDelivered.
-    throw new Error(`resume: input is not JSON-serializable (${(err as Error).message}) — a resume answer must round-trip to the DO`);
+    throw new Error(`resume: ${culprit} is not JSON-serializable (${(err as Error).message}) — a resume must round-trip to the DO`);
   }
 }
 

package/src/agent-native.ts

@@ -9,6 +9,7 @@
 
 import {
   AgentSession,
+  grantAnswer,
   withSystem,
   type ChannelPolicy,
   type EventSink,
@@ -363,7 +364,10 @@ export function mountAgent(
     // HITL: answer a parked turn and stream its continuation (the approval-button path).
     resumeStream: async function* (o) {
       const session = runtime.session(agent.name, o.session ?? "default");
-      const { turnId } = session.resume(o.turnId, o.inputId, o.input, { by: o.by });
+      // A { policy } answerer is the app's call (#261): decided here, before the synchronous
+      // resume, so resume-then-subscribe stays free of awaits.
+      const granted = await grantAnswer(session, o, agent.authorizeAnswer);
+      const { turnId } = session.resume(o.turnId, o.inputId, o.input, { by: o.by, granted });
       yield* observeTurnEvents(session, turnId);
     },
     // SESSION RESET (#129): same seam as durableChannelSurface — the in-process runtimes'

package/src/build.ts

@@ -314,7 +314,9 @@ export async function juneBuild(
   // The Link header is frozen here from the same builder the pipeline uses, so
   // the static and dynamic surfaces advertise identically. The adapter wraps the
   // portable pipeline for its target (workers() → withAssets).
-  const linkHeader = buildLinkHeader(frozen.agent);
+  // (catalogs: the same publication rule as the pipeline's catalogOrigin — a
+  // basePath site publishes no /.well-known catalog, so it links none.)
+  const linkHeader = buildLinkHeader(frozen.agent, { catalogs: !frozen.document.basePath });
   const adapterEntry = adapter.entry({ linkHeader });
 
   // Resources (when declared) are bound from the worker's env (env.DB → D1) by
@@ -506,7 +508,16 @@ ${doClass}`;
   if (cssAsset) manifest.document.styles = `/${cssAsset}`; // prerendered HTML links the hashed sheet
   if (clientAsset) manifest.document.clientScript = `/${clientAsset}`;
   if (moduleCssAsset) manifest.document.moduleStyles = `/${moduleCssAsset}`;
-  const worker = createWorker(manifest);
+  // A static site has no server: /mcp (and the WebMCP tools that proxy to it)
+  // and the HTTP API (POST /api/<id>, /openapi.json) do not exist there. Render
+  // with both projected out, so the published files advertise only what is
+  // deployed: llms.txt drops its MCP and HTTP API sections, the catalogs and the
+  // generated skill list neither, pages register no WebMCP tools.
+  const isStatic = adapter.capabilities.runtime === "static";
+  if (isStatic) manifest.agent = { ...manifest.agent, mcp: false, api: false, webmcp: false };
+  // The static() target prerenders its sitemap too; that build is where the
+  // route contract lets `staticPaths` run, so its sitemap lists those pages.
+  const worker = createWorker(manifest, { staticBuild: isStatic });
   let hasAssets = false;
 
   // ---- public/ → assets/ : verbatim static files (favicon, images, fonts) ----
@@ -567,7 +578,6 @@ ${doClass}`;
   // dynamic routes via their staticPaths, and write <stem>/index.html so clean URLs
   // resolve on a dumb file host with no rewrite server. Other targets keep the
   // opt-in `prerender: true` behavior and the flat <stem>.html naming (byte-identical).
-  const isStatic = adapter.capabilities.runtime === "static";
   const i18n = frozen.i18n;
 
   // Render ONE route pathname through the worker → HTML (+ .md/.json projections).
@@ -604,6 +614,17 @@ ${doClass}`;
 
   // Locale variants a static route is emitted at: no i18n → [path]; with i18n → one
   // per locale (defaultLocale keeps the bare path, others get their localeHref prefix).
+  // A static build is ONE file tree on ONE host: a locale on its own domain has no
+  // path in it (and a basePath can't apply there), so say so instead of failing
+  // later with a prerender 404.
+  if (isStatic && i18n) {
+    const onDomain = Object.keys(i18n.locales).filter((l) => i18n.locales[l]!.domain);
+    if (onDomain.length) {
+      throw new Error(
+        `[june build] the static() target serves one host, so i18n locales with their own domain are not supported (${onDomain.join(", ")}). Give them a path prefix instead, e.g. { path: "/${onDomain[0]}" }.`,
+      );
+    }
+  }
   const localeVariants = (path: string): string[] =>
     isStatic && i18n
       ? [...new Set(Object.keys(i18n.locales).map((l) => localeHref(i18n, path, l)))]
@@ -624,6 +645,9 @@ ${doClass}`;
       const sp = dyn.def.staticPaths;
       if (!sp) continue;
       const paths = typeof sp === "function" ? await sp() : sp;
+      // Resolve a producer ONCE: the prerendered sitemap below reads this same
+      // def, so it lists exactly the set prerendered here without a second call.
+      dyn.def.staticPaths = paths;
       for (const p of paths) await prerenderOne(p, dyn.def);
     }
     // Framework surfaces the worker would otherwise generate on the fly. Guarded on
@@ -635,11 +659,45 @@ ${doClass}`;
       ["/llms.txt", "llms.txt"],
       ["/sitemap.xml", "sitemap.xml"],
     ];
-    for (const [reqPath, file] of extra) {
+    // A sitemap needs absolute URLs, and the prerender host is a placeholder: with
+    // no public origin configured the pipeline answers 404 for it (and the loop
+    // below skips it), so say why rather than silently ship no sitemap.
+    if (manifest.agent.discovery && !manifest.document.site.url && !manifest.document.deployOrigin) {
+      console.warn(
+        "[june build] no sitemap.xml: set site.url (or deploy.domain) in june.config.ts so its URLs are absolute.",
+      );
+    }
+    // The agent catalogs (ARD, Agent Skills) — JSON/Markdown files a static host
+    // can serve as-is — only when this site publishes them: agent discovery on, a
+    // root deploy (a basePath site doesn't own /.well-known), and a known public
+    // origin (the files name absolute URLs). Same rule as the pipeline's
+    // catalogOrigin, stated here too so an app catch-all route can never answer
+    // these paths into the build. The generated skill's path carries its name, so
+    // it is read back from the index.
+    const doc = manifest.document;
+    if (manifest.agent.discovery && !doc.basePath && (doc.site.url || doc.deployOrigin)) {
+      extra.push(
+        ["/.well-known/ai-catalog.json", ".well-known/ai-catalog.json"],
+        ["/.well-known/ard.json", ".well-known/ard.json"],
+        ["/.well-known/agent-skills/index.json", ".well-known/agent-skills/index.json"],
+      );
+    }
+    for (let i = 0; i < extra.length; i++) {
+      const [reqPath, file] = extra[i]!;
       const res = await worker.fetch(new Request(`${PRERENDER_ORIGIN}${reqPath}`));
       if (!res.ok) continue;
-      await writeFile(join(assetsDir, file), Buffer.from(await res.arrayBuffer()));
+      const bytes = Buffer.from(await res.arrayBuffer());
+      await mkdir(dirname(join(assetsDir, file)), { recursive: true });
+      await writeFile(join(assetsDir, file), bytes);
       hasAssets = true;
+      if (file.endsWith("agent-skills/index.json")) {
+        const index = JSON.parse(bytes.toString("utf8")) as { skills?: Array<{ url?: string }> };
+        for (const s of index.skills ?? []) {
+          if (!s.url) continue;
+          const p = new URL(s.url, PRERENDER_ORIGIN).pathname;
+          extra.push([p, p.slice(1)]);
+        }
+      }
     }
     // 404.html — GitHub Pages serves it for any unmatched URL. A deliberately-missing
     // path renders June's not-found HTML (body is written regardless of the 404 status).

package/src/llms-links.ts

@@ -0,0 +1,96 @@
+// /llms.txt links, collected from the routes themselves. Each route may export
+// `llms` (see LlmsEntry in @junejs/core/route): a static route defaults to one link
+// under "Pages" built from its static metadata; a dynamic route — a [param]
+// template an agent can't fetch — lists each real page it serves, or is skipped.
+// Links point at the markdown projection (<path>.md) unless the route turned md off,
+// so an agent reads the page rather than its HTML (llmstxt.org's recommendation).
+import type { LlmsLink, SitemapPage } from "@junejs/core/discovery";
+import type { LlmsEntry } from "@junejs/core/route";
+
+import type { RouteResolver } from "./pipeline";
+
+const DEFAULT_SECTION = "Pages";
+
+const mdPath = (path: string) => (path === "/" ? "/index.md" : `${path.replace(/\/+$/, "")}.md`);
+
+export async function collectLlmsLinks(origin: string, routes: string[], resolve: RouteResolver): Promise<LlmsLink[]> {
+  const links: LlmsLink[] = [];
+  const seen = new Set<string>();
+  for (const route of routes) {
+    // A dynamic template resolves against its own pattern ("/docs/[slug]" matches
+    // /docs/:slug), which is all we need: the route definition, not its data.
+    const resolved = await resolve(route);
+    if (!resolved || !("def" in resolved)) continue; // resource routes have no page to list
+    const { def } = resolved;
+    if (def.llms === false) continue;
+
+    const dynamic = route.includes("[");
+    const declared = typeof def.llms === "function" ? await def.llms() : def.llms;
+    const entries: LlmsEntry[] = declared ? (Array.isArray(declared) ? declared : [declared]) : dynamic ? [] : [{}];
+    // Static metadata only: a metadata FUNCTION needs loader data we don't run here.
+    const meta = typeof def.metadata === "object" ? def.metadata : undefined;
+
+    for (const entry of entries) {
+      const path = entry.path ?? (dynamic ? undefined : route);
+      if (!path) continue; // a dynamic entry must name its page
+      const url = origin + (def.md === false ? path : mdPath(path));
+      // dedupe on the FINAL url: "/a" and "/a/" both render /a.md, so they're one page
+      if (seen.has(url)) continue;
+      seen.add(url);
+      const own = path === route; // the route's own page → its metadata describes it
+      links.push({
+        title: entry.title ?? (own ? meta?.title : undefined) ?? path,
+        url,
+        description: entry.description ?? (own ? meta?.description : undefined),
+        section: entry.section ?? DEFAULT_SECTION,
+        optional: entry.optional === true,
+      });
+    }
+  }
+  return links;
+}
+
+// /sitemap.xml pages, enumerated like /llms.txt. A static route is one page; a
+// dynamic route lists its real pages via its `llms` entries (their `lastModified`
+// becomes <lastmod>) — the runtime-safe hook /llms.txt already runs. A route
+// that names none stays out: a [param] template isn't a URL. Resource routes
+// (route.*) are machine endpoints, not pages. `llms = false` keeps a static
+// route listed (its URL is known without entries); on a dynamic route it leaves
+// no entries, so its pages drop out of the runtime sitemap too.
+// `staticPaths` join in only when opts.staticPaths is set — the static() build's
+// prerender, the one place the route contract runs them. Even then they're
+// skipped under i18n: they arrive locale-prefixed, while the sitemap derives
+// each page's locale variants from its canonical path.
+export async function collectSitemapPages(
+  routes: string[],
+  resolve: RouteResolver,
+  opts: { i18n?: boolean; staticPaths?: boolean } = {},
+): Promise<SitemapPage[]> {
+  const pages = new Map<string, SitemapPage>();
+  const add = (path: string, lastModified?: string | Date) => {
+    const key = path === "/" ? "/" : path.replace(/\/+$/, "");
+    const prev = pages.get(key);
+    if (!prev) pages.set(key, lastModified ? { path: key, lastModified } : { path: key });
+    else if (lastModified && !prev.lastModified) prev.lastModified = lastModified;
+  };
+  for (const route of routes) {
+    const resolved = await resolve(route);
+    if (!resolved || !("def" in resolved)) continue;
+    const { def } = resolved;
+    const dynamic = route.includes("[");
+    const declared = def.llms ? (typeof def.llms === "function" ? await def.llms() : def.llms) : undefined;
+    const entries: LlmsEntry[] = declared ? (Array.isArray(declared) ? declared : [declared]) : [];
+    // A static route is exactly one URL — its own. An entry naming another path
+    // (an llms.txt pointer elsewhere) is not a page this route serves.
+    if (!dynamic) {
+      add(route, entries.find((e) => (e.path ?? route) === route)?.lastModified);
+      continue;
+    }
+    for (const e of entries) if (e.path) add(e.path, e.lastModified);
+    if (opts.staticPaths && !opts.i18n && def.staticPaths) {
+      const sp = typeof def.staticPaths === "function" ? await def.staticPaths() : def.staticPaths;
+      for (const p of sp) add(p);
+    }
+  }
+  return [...pages.values()];
+}