@teamscala/service-boot 0.23.430 → 0.23.432

package/src/register-registry-page-route/apply-page-branding.ts

@@ -12,6 +12,74 @@
  * explicit parameters.
  */
 
+/**
+ * /sign-in brand override: a shared org-scoped link 302→/sign-in for the
+ * unauthed crawler (WhatsApp), which saw the service's default website
+ * brand (the platform owner). The callbackURL carries the destination org
+ * — override resolved.brand (before the title/meta/og are built from it)
+ * so the page reflects the org the visitor is signing in to. Scoped to
+ * /sign-in; resource pages keep their own brand.
+ *
+ * The org is segment 1 of the canonical portal shape /<websiteId>/<orgId>/
+ * <path>, NOT segment 0 (the website id): reading segment 0 fed a website id
+ * into fetchOrganisationPageBranding, which resolved no org and left the
+ * default (super-admin) brand — the cross-tenant mis-branding this override
+ * exists to prevent (portal-branding-resolves-page-org-first, 2026-07-21).
+ * Shared helper so this and bind-page-handler cannot drift on the answer.
+ */
+
+// Why: /sign-in brand override: a shared org-scoped link 302→/sign-…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+/**
+ * brand-is-org-owned-full-scheme, reconciled with page-org-first
+ * (portal-branding-resolves-page-org-first): the session override now
+ * personalizes ONLY platform pages (page org === website owning-org).
+ * Tenant pages keep their resolved page-org brand — the page is
+ * authoritative, the menu switcher changes which tenant's pages you
+ * view. Anonymous/public (no session) keeps the resolved brand. Same
+ * fetchOrganisationPageBranding pattern as the /sign-in brand override.
+ *
+ * A PUBLIC PAGE IS NEVER PERSONALISED TO THE READER'S ORG. Personalising
+ * the brand is right for a portal — you are looking at your own
+ * workspace. It is wrong for a public document, which belongs to the org
+ * that PUBLISHED it and must look identical to every reader.
+ *
+ * Measured 2026-08-17: the Launcha Authority Blueprint, owned by GMG
+ * APAC, rendered correctly for an anonymous customer and in GBG Indo's
+ * navy with the scala logo for any signed-in staff member — so the two
+ * people checking it before it went to clients were the only two who
+ * could not see what a client sees. Silent, and inverted: the reviewers
+ * got the wrong page.
+ */
+
+// Why: brand-is-org-owned-full-scheme, reconciled with page-org-fir…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+/**
+ * BRAND FROM THE ORG THAT OWNS THE RESOURCE, not the website's owner.
+ * A public resource page (an assessment report, a shared document) is
+ * hosted on a shared website but BELONGS to a tenant. resolvePageBrand
+ * reads pageData.orgId, which is the WEBSITE's org, so every tenant's
+ * report rendered the host org's logo and palette.
+ *
+ * Measured 2026-08-17: the Launcha Authority Blueprint is owned by GMG
+ * APAC (#FF4500, launcha logo) and rendered with GBG Indo's navy and
+ * scala mark, because both pages live on the shared "Public Pages"
+ * site. The loader had already resolved the right org — nothing
+ * consumed it.
+ *
+ * `brand_org_path` names where the owning org id lives in the resolved
+ * loader data (e.g. "quiz.organisation_id"), so which resource owns the
+ * brand is a ROW, never a per-service branch
+ * (`business-logic-is-rows-plus-executors`). Absent or unresolvable,
+ * the website's org stands — this can only ever narrow the brand to a
+ * more specific owner, never blank it.
+ */
+
+// Why: BRAND FROM THE ORG THAT OWNS THE RESOURCE, not the website's…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { fetchOrganisationPageBranding } from "@teamscala/db/fetch-organisation-page-branding";
 import { getPlatformOrgId } from "@teamscala/db/registry/platform";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
@@ -43,21 +111,6 @@ function spreadBranding(
 	};
 }
 
-/**
- * /sign-in brand override: a shared org-scoped link 302→/sign-in for the
- * unauthed crawler (WhatsApp), which saw the service's default website
- * brand (the platform owner). The callbackURL carries the destination org
- * — override resolved.brand (before the title/meta/og are built from it)
- * so the page reflects the org the visitor is signing in to. Scoped to
- * /sign-in; resource pages keep their own brand.
- *
- * The org is segment 1 of the canonical portal shape /<websiteId>/<orgId>/
- * <path>, NOT segment 0 (the website id): reading segment 0 fed a website id
- * into fetchOrganisationPageBranding, which resolved no org and left the
- * default (super-admin) brand — the cross-tenant mis-branding this override
- * exists to prevent (portal-branding-resolves-page-org-first, 2026-07-21).
- * Shared helper so this and bind-page-handler cannot drift on the answer.
- */
 export async function applySignInBrandOverride(
 	resolved: Record<string, unknown>,
 	request: Request,
@@ -86,27 +139,6 @@ export async function applySignInBrandOverride(
 	}
 }
 
-/**
- * brand-is-org-owned-full-scheme, reconciled with page-org-first
- * (portal-branding-resolves-page-org-first): the session override now
- * personalizes ONLY platform pages (page org === website owning-org).
- * Tenant pages keep their resolved page-org brand — the page is
- * authoritative, the menu switcher changes which tenant's pages you
- * view. Anonymous/public (no session) keeps the resolved brand. Same
- * fetchOrganisationPageBranding pattern as the /sign-in brand override.
- *
- * A PUBLIC PAGE IS NEVER PERSONALISED TO THE READER'S ORG. Personalising
- * the brand is right for a portal — you are looking at your own
- * workspace. It is wrong for a public document, which belongs to the org
- * that PUBLISHED it and must look identical to every reader.
- *
- * Measured 2026-08-17: the Launcha Authority Blueprint, owned by GMG
- * APAC, rendered correctly for an anonymous customer and in GBG Indo's
- * navy with the scala logo for any signed-in staff member — so the two
- * people checking it before it went to clients were the only two who
- * could not see what a client sees. Silent, and inverted: the reviewers
- * got the wrong page.
- */
 export async function applySessionOrgBranding(
 	pageData: Record<string, unknown>,
 	renderMode: string | undefined,
@@ -141,26 +173,6 @@ export async function applySessionOrgBranding(
 	}
 }
 
-/**
- * BRAND FROM THE ORG THAT OWNS THE RESOURCE, not the website's owner.
- * A public resource page (an assessment report, a shared document) is
- * hosted on a shared website but BELONGS to a tenant. resolvePageBrand
- * reads pageData.orgId, which is the WEBSITE's org, so every tenant's
- * report rendered the host org's logo and palette.
- *
- * Measured 2026-08-17: the Launcha Authority Blueprint is owned by GMG
- * APAC (#FF4500, launcha logo) and rendered with GBG Indo's navy and
- * scala mark, because both pages live on the shared "Public Pages"
- * site. The loader had already resolved the right org — nothing
- * consumed it.
- *
- * `brand_org_path` names where the owning org id lives in the resolved
- * loader data (e.g. "quiz.organisation_id"), so which resource owns the
- * brand is a ROW, never a per-service branch
- * (`business-logic-is-rows-plus-executors`). Absent or unresolvable,
- * the website's org stands — this can only ever narrow the brand to a
- * more specific owner, never blank it.
- */
 export async function applyBrandOrgPath(
 	pageData: Record<string, unknown>,
 	resolved: Record<string, unknown>,

package/src/register-registry-page-route/graph-cache.ts

@@ -1,6 +1,6 @@
 /**
  * @system ui-service-boot
- * @status handwritten @indivisible-unit
+ * @status handwritten @indivisible-unit owner=unassigned reason=91 lines; pre-2026-08-27 exemption, unreviewed
  * @edit edit directly
  *
  * The two SWR loader-graph caches (static-shell + parameterised routes) for the
@@ -22,6 +22,27 @@
  * so handing a cached tree out twice would ship request A's resolved data to
  * request B (ssr-first-tick-parity). Clone-on-get stays local to the caller.
  */
+/**
+ * Stale-while-revalidate read of a cached loader graph.
+ *
+ * - Fresh hit (within ttlMs): return the cached graph, no refresh.
+ * - Stale hit (within ttlMs + staleTtlMs): return the cached graph AND fire ONE
+ *   background refresh via cache.refreshInBackground — single-flight (deduped
+ *   against the cache's in-flight map), never rejects, leaves the stale entry in
+ *   place on failure. The caller deep-clones the returned value before use.
+ * - Miss (past staleTtlMs, or never cached): return undefined — the caller
+ *   resolves synchronously and cache.set()s the clone.
+ *
+ * The refresh callback must return a graph safe to store. To SKIP caching a
+ * refresh result (e.g. a primary-missing / dead-link graph that must stay
+ * per-request so a just-created record appears immediately), the callback THROWS
+ * — refreshInBackground catches it, leaves the stale entry, and logs one line
+ * (an observable dead-link signal, not a hard error).
+ */
+
+// Why: Stale-while-revalidate read of a cached loader graph.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { createCache } from "@teamscala/cache/create-cache";
 
 // The structural surface readCachedGraph touches (getWithMeta + refreshInBackground).
@@ -61,23 +82,6 @@ export const paramRouteGraphCache = createCache<unknown>(
 	{ maxSize: 256, ttlMs: 15_000, staleTtlMs: 285_000 },
 );
 
-/**
- * Stale-while-revalidate read of a cached loader graph.
- *
- * - Fresh hit (within ttlMs): return the cached graph, no refresh.
- * - Stale hit (within ttlMs + staleTtlMs): return the cached graph AND fire ONE
- *   background refresh via cache.refreshInBackground — single-flight (deduped
- *   against the cache's in-flight map), never rejects, leaves the stale entry in
- *   place on failure. The caller deep-clones the returned value before use.
- * - Miss (past staleTtlMs, or never cached): return undefined — the caller
- *   resolves synchronously and cache.set()s the clone.
- *
- * The refresh callback must return a graph safe to store. To SKIP caching a
- * refresh result (e.g. a primary-missing / dead-link graph that must stay
- * per-request so a just-created record appears immediately), the callback THROWS
- * — refreshInBackground catches it, leaves the stale entry, and logs one line
- * (an observable dead-link signal, not a hard error).
- */
 export function readCachedGraph(
 	cache: GraphCache,
 	key: string,

package/src/register-registry-page-route/meta-title.ts

@@ -1,6 +1,6 @@
 /**
  * @system ui-service-boot
- * @status handwritten @indivisible-unit
+ * @status handwritten @indivisible-unit owner=unassigned reason=82 lines; pre-2026-08-27 exemption, unreviewed
  * @edit edit directly
  *
  * Meta/title helpers for the route registrar: interpolate the route's
@@ -13,6 +13,29 @@
  * by construction, dead on exactly the pages the type exists for (Valencia's
  * finding). composePageTitle (+ the org-prefix flag) owns titles end to end.
  */
+/**
+ * THE ONE SUBJECT DERIVATION. What a page is ABOUT — the entity whose name the
+ * browser tab should carry.
+ *
+ * This existed as THREE hand-written `||` chains, one per render branch in
+ * resolve-page-data, and they had already diverged: two ordered form before
+ * proposal, the third ordered proposal first. So which resource named the page
+ * depended on which branch happened to render it, silently.
+ *
+ * The divergence is the cheap half of the cost. The expensive half is that a
+ * correction has to be applied three times to work, and applying it twice looks
+ * exactly like applying it correctly — measured 2026-08-17, when a fix to the
+ * quiz subject was shipped, installed and verified present in the bundle while
+ * the page kept its old title, because the branch that rendered it held the
+ * second copy.
+ *
+ * One chain, one precedence, one place to change. Adding a resource type is an
+ * edit here rather than a fourth branch in three files.
+ */
+
+// Why: THE ONE SUBJECT DERIVATION. What a page is ABOUT — the entit…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { interpolateMeta } from "../resolve-from-loader-config.ts";
 
 export function buildMetaFromContext(
@@ -38,25 +61,6 @@ export function resolvePageMetaTitle(
 	);
 }
 
-/**
- * THE ONE SUBJECT DERIVATION. What a page is ABOUT — the entity whose name the
- * browser tab should carry.
- *
- * This existed as THREE hand-written `||` chains, one per render branch in
- * resolve-page-data, and they had already diverged: two ordered form before
- * proposal, the third ordered proposal first. So which resource named the page
- * depended on which branch happened to render it, silently.
- *
- * The divergence is the cheap half of the cost. The expensive half is that a
- * correction has to be applied three times to work, and applying it twice looks
- * exactly like applying it correctly — measured 2026-08-17, when a fix to the
- * quiz subject was shipped, installed and verified present in the bundle while
- * the page kept its old title, because the branch that rendered it held the
- * second copy.
- *
- * One chain, one precedence, one place to change. Adding a resource type is an
- * edit here rather than a fourth branch in three files.
- */
 export function resolveEntityTitle(resolved: Record<string, unknown>): string | undefined {
 	const pick = (key: string, ...fields: string[]): string | undefined => {
 		const row = resolved[key] as Record<string, unknown> | undefined;

package/src/register-registry-page-route/prefetch-org-id.ts

@@ -9,8 +9,6 @@
  * register-registry-page-route.ts.
  */
 
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
 /**
  * Prefer segment 1; fall back to segment 0 only when segment 1 is not a
  * UUID (the single-UUID shape, which is live and supported — NOT
@@ -28,6 +26,12 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  * UUIDs: the prefetch simply warmed a session against the wrong tenant
  * (found 2026-07-21).
  */
+
+// Why: Prefer segment 1; fall back to segment 0 only when segment 1…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
 export function resolveAiOrgId(pathname: string): string | undefined {
 	const pathSegments = pathname.split("/").filter(Boolean);
 	return UUID_RE.test(pathSegments[1] ?? "")

package/src/register-registry-page-route/proposal-approval-email-token.ts

@@ -12,9 +12,6 @@
  * stamping that touch no network. Sharing a file made an I/O-bound resolver
  * look like a pure formatter.
  */
-import { getServerClient } from "../page-server-orpc/server-client.ts";
-
-
 /**
  * Resolve the `{{approvalEmail}}` placeholder in a proposal page's button props
  * (e.g. the Approve CTA) in place. Routing: the organisation's registered
@@ -27,6 +24,11 @@ import { getServerClient } from "../page-server-orpc/server-client.ts";
  * pages; other registry pages are untouched.
  */
 
+// Why: Resolve the `{{approvalEmail}}` placeholder in a proposal pa…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import { getServerClient } from "../page-server-orpc/server-client.ts";
+
 export async function applyApprovalEmailToken(
 	pageData: Record<string, unknown>,
 	proposal: { created_by?: string } | undefined,

package/src/register-registry-page-route/run-content-gates.ts

@@ -50,10 +50,8 @@ export async function runContentGatesForPage(
 		if (withholdsContent(entry)) gateOutcomes.push(outcome);
 	}
 
-	// THE ASSISTANT IS A ROW, AND THIS IS THE ONE PLACE IT IS APPLIED.
-	// It used to be a call inside each gate's onAuthorized plus an entry
-	// in the hardcoded gate sequence above, so a third resource type
-	// meant editing this file. Now any page declaring `assistant` gets
+	// THE ASSISTANT IS A ROW, AND THIS IS THE ONE PLACE IT IS APPLIED. It used to be a call inside each gate's onAuthorized plus an entry
+	// in the hardcoded gate sequence above, so a third resource type meant editing this file. Now any page declaring `assistant` gets
 	// one and no page without the key does.
 	//
 	// GATED PAGES ONLY WHEN AUTHORIZED. The launcher's runtime context is

package/src/register-registry-page-route.ts

@@ -292,8 +292,7 @@ export async function registerRegistryPageRoute(
 				serviceSlug,
 			);
 			warnUncoveredBlocks(pageData, components, serviceSlug, params.path, log);
-			// Detached (NOT awaited into the response). prefetchAiChatSession ->
-			// createOrRestore is DB-heavy (~1.1s), per-user, and uncached, and was
+			// Detached (NOT awaited into the response). prefetchAiChatSession -> createOrRestore is DB-heavy (~1.1s), per-user, and uncached, and was
 			// awaited on EVERY loadData — the dominant board loadMs cost (confirmed
 			// aiChatPrefetch=1145ms = the full loadMs). Fire it in the background so
 			// it still warms the server-side session (users who open chat find it

package/src/register-static-assets.ts

@@ -11,6 +11,7 @@
  */
 
 import { join } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
 import { etag } from "hono/etag";
 import { buildErrorReport } from "@teamscala/os/errors/error-report";
@@ -62,10 +63,8 @@ export async function registerStaticAssets(
 		}
 	});
 
-	// Build-id: the content hash of the CURRENT client bundle, read FRESH from
-	// the asset manifest on every call (never a process-pinned copy) so a
-	// post-restart rebuild reports its new id immediately. The client self-heal
-	// (page-client/boot/build-self-heal) polls this on tab refocus; if it differs
+	// Build-id: the content hash of the CURRENT client bundle, read FRESH from the asset manifest on every call (never a process-pinned copy) so a
+	// post-restart rebuild reports its new id immediately. The client self-heal (page-client/boot/build-self-heal) polls this on tab refocus; if it differs
 	// from the build the tab booted with, a new build shipped and the open tab is
 	// stale → it reloads. no-store HTML + immutable hashed assets already prevent
 	// staleness on every FRESH load; this is what closes the one remaining hole —
@@ -81,7 +80,9 @@ export async function registerStaticAssets(
 			const raw = await Bun.file(path).text();
 			const manifest = JSON.parse(raw) as { hydratePath?: string };
 			build = /hydrate-([a-z0-9]+)\.js/.exec(manifest.hydratePath ?? "")?.[1] ?? "dev";
-		} catch {}
+		} catch (error) {
+			getAppLogger().warn("[register-static-assets] asset manifest unreadable — build label falls back to dev", error);
+		}
 		return c.json({ build }, 200, { "cache-control": "no-store" });
 	});
 

package/src/resolve-app-base-url.ts

@@ -13,16 +13,23 @@
 
 import { ServiceInstallConfigSchema } from "@teamscala/db-validation/registry-schemas/service-install";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { createCache } from "@teamscala/cache/create-cache";
 
-let cachedAppUrl: string | null = null;
+const appUrlCache = createCache<string>("service-boot:app-base-url", {
+	ttlMs: Number.POSITIVE_INFINITY,
+	maxSize: 1,
+});
 
 export async function resolveAppBaseUrl(): Promise<string> {
-	if (cachedAppUrl) return cachedAppUrl;
+	const hit = appUrlCache.get("default");
+	if (hit) return hit;
 	try {
 		const config = await loadRegistryConfig("service_install", "scala-projects", ServiceInstallConfigSchema);
-		cachedAppUrl = `https://${config.public_hostname}`;
+		const url = `https://${config.public_hostname}`;
+		appUrlCache.set("default", url);
+		return url;
 	} catch {
-		cachedAppUrl = "https://projects.scala.business";
+		appUrlCache.set("default", "https://projects.scala.business");
+		return "https://projects.scala.business";
 	}
-	return cachedAppUrl;
 }

package/src/resolvers/portal-route-paths.ts

@@ -13,17 +13,6 @@
  * `/<last-segment>-toolbar`. Pages without a matching toolbar page simply
  * resolve an empty toolbar region (the source is declared optional).
  */
-export interface ResolverArgs {
-	input: Record<string, unknown>;
-	client: unknown;
-	params: Record<string, unknown>;
-}
-
-// Canonical portal URL shape: /<websiteId>/<organisationId>/<builda path...>.
-// Segment 0 is the portal WEBSITE id; segment 1 is the ORG id. Shared by the
-// resolver below and by extractOrgIdFromCallbackPath (the /sign-in brand path).
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
 /**
  * Extract the organisation id from a portal-shaped callback/path — the single
  * authority for "which segment is the org" so the sign-in brand resolver and the
@@ -41,6 +30,21 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  * correct-org improvement for the two-UUID portal shape). Returns undefined when
  * neither leading segment is a UUID.
  */
+
+// Why: Extract the organisation id from a portal-shaped callback/pa…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+export interface ResolverArgs {
+	input: Record<string, unknown>;
+	client: unknown;
+	params: Record<string, unknown>;
+}
+
+// Canonical portal URL shape: /<websiteId>/<organisationId>/<builda path...>.
+// Segment 0 is the portal WEBSITE id; segment 1 is the ORG id. Shared by the
+// resolver below and by extractOrgIdFromCallbackPath (the /sign-in brand path).
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
 export function extractOrgIdFromCallbackPath(callbackUrl: string): string | undefined {
 	const segs = callbackUrl.split("?")[0].split("/").filter(Boolean);
 	if (UUID_RE.test(segs[1] ?? "")) return segs[1];

package/src/resource-chat-inject.ts

@@ -20,6 +20,90 @@
  * (fail-soft).
  */
 
+/**
+ * THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS FILE.
+ *
+ * `ai_agents` already carries a column for every one of them -- name,
+ * welcome_message, conversation_starters, primary_color -- and on 2026-08-19
+ * both live agents had welcome_message NULL and conversation_starters empty
+ * while the copy sat spelled in TypeScript here and in proposal-chat-inject.
+ * The intended home existed, sat blank, and the hardcoded copy won, so nobody
+ * could change a word the assistant says without a code change and a deploy.
+ * Two copies of one fact with the stale one winning silently is exactly
+ * `information-exists-in-one-location`.
+ *
+ * `launchLabel` and `placeholder` remain caller arguments only because no
+ * column holds them yet.
+ */
+
+// Why: THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS F…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+/**
+ * The rendered content tree to append the launcher to.
+ *
+ * WHICH KEYS EXIST IS A ROW FACT, SO IT IS NOT SPELLED HERE. A page's resolved
+ * sources and its region slots are declared on the `resource_loader` row, and
+ * the caller has already read that row — so it passes `regionSlots` in. An
+ * earlier draft of this function named "page", "body", "header" and "footer" as
+ * literals, which is a loader row copied into TypeScript, free to drift from it
+ * the moment a loader is edited (`identity-is-imported-never-spelled`).
+ *
+ * A FLAT PAGE KEEPS ITS CONTENT UNDER `page`; A REGION-SLOT PAGE DOES NOT.
+ * Proposals and agreements resolve one `page` source, so the original injector
+ * read `resolved.page.puck_data.content` and returned early when it was absent.
+ * A generated report resolves region slots instead, so that early return fired
+ * and the assistant was silently missing — the same failure shape as the dead
+ * block name, since fail-soft injection logs nothing and the page looks fine.
+ *
+ * ANY RENDERED REGION WILL DO, SO THE FIRST DECLARED ONE IS TAKEN. The launcher
+ * renders `position: fixed` at `zIndex: 50`, anchored to the viewport and not
+ * to its container, so it appears identically whichever region carries it. That
+ * is what makes "first declared region holding a content tree" a derivation
+ * rather than a guess dressed up as one: there is no better region to prefer.
+ *
+ * `PAGE_SOURCE_KEY` is the platform's existing name for a flat page's body
+ * source — the same convention `decideContentPageFloor` already keys on in the
+ * caller. One shared convention, not a per-resource list.
+ */
+
+// Why: The rendered content tree to append the launcher to.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+/**
+ * Serialise EVERYTHING THIS VIEWER MAY SEE as text for the assistant.
+ *
+ * BOTH THE RESULT AND THE RENDERED DOCUMENT, BECAUSE NEITHER IS SUFFICIENT.
+ * The original serialiser sent the resource record plus the page's content
+ * tree, which is exactly right for a proposal — the proposal's substance IS in
+ * its blocks. It is wrong for anything the platform GENERATES a document from.
+ * A report's body page is a shared template (one `builda_pages` row serves
+ * every respondent) so the content tree holds headings and layout and not one
+ * personal fact, while the substance — the answers, the category scores, the
+ * computed narrative and bands — sits in sibling resolved keys the serialiser
+ * never looked at. Sending only the page would give the assistant a form with
+ * no answers; sending only the record would leave it unable to discuss what the
+ * reader is actually looking at. An assessment result GENERATES a report, so
+ * the assistant needs both halves of that.
+ *
+ * NO KEY IS NAMED, INCLUDED OR EXCLUDED. The loader row decides what a page
+ * resolves; this walks whatever that produced. A draft carried a `CHROME_KEYS`
+ * exclusion list dropping brand, website, header and footer — every one of them
+ * a loader source key, which is to say database facts hardcoded here to save a
+ * few hundred tokens of colours and navigation markup. Not a trade worth a
+ * literal that goes stale in silence. A loader resolving a new source reaches
+ * the assistant with no edit here (`offered-is-derived`).
+ *
+ * IT CANNOT OUTRUN THE GATE, BY CONSTRUCTION. This runs AFTER every content
+ * gate, and a gate withholds by REMOVING content from this same graph. So
+ * "everything in the graph" and "everything this viewer may see" are the same
+ * set, and they cannot drift — which is what makes serialising the whole graph
+ * safe rather than reckless.
+ */
+
+// Why: Serialise EVERYTHING THIS VIEWER MAY SEE as text for the ass…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { getServerClient } from "./page-server-orpc/server-client.ts";
@@ -61,21 +145,6 @@ export interface ResourceChatOptions {
 	regionSlots?: readonly string[];
 }
 
-/**
- * THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS FILE.
- *
- * `ai_agents` already carries a column for every one of them -- name,
- * welcome_message, conversation_starters, primary_color -- and on 2026-08-19
- * both live agents had welcome_message NULL and conversation_starters empty
- * while the copy sat spelled in TypeScript here and in proposal-chat-inject.
- * The intended home existed, sat blank, and the hardcoded copy won, so nobody
- * could change a word the assistant says without a code change and a deploy.
- * Two copies of one fact with the stale one winning silently is exactly
- * `information-exists-in-one-location`.
- *
- * `launchLabel` and `placeholder` remain caller arguments only because no
- * column holds them yet.
- */
 export interface AgentPresentation {
 	title?: string;
 	welcomeMessage?: string;
@@ -147,33 +216,6 @@ function puckContentOf(value: unknown): unknown[] | null {
 	return Array.isArray(content) ? content : null;
 }
 
-/**
- * The rendered content tree to append the launcher to.
- *
- * WHICH KEYS EXIST IS A ROW FACT, SO IT IS NOT SPELLED HERE. A page's resolved
- * sources and its region slots are declared on the `resource_loader` row, and
- * the caller has already read that row — so it passes `regionSlots` in. An
- * earlier draft of this function named "page", "body", "header" and "footer" as
- * literals, which is a loader row copied into TypeScript, free to drift from it
- * the moment a loader is edited (`identity-is-imported-never-spelled`).
- *
- * A FLAT PAGE KEEPS ITS CONTENT UNDER `page`; A REGION-SLOT PAGE DOES NOT.
- * Proposals and agreements resolve one `page` source, so the original injector
- * read `resolved.page.puck_data.content` and returned early when it was absent.
- * A generated report resolves region slots instead, so that early return fired
- * and the assistant was silently missing — the same failure shape as the dead
- * block name, since fail-soft injection logs nothing and the page looks fine.
- *
- * ANY RENDERED REGION WILL DO, SO THE FIRST DECLARED ONE IS TAKEN. The launcher
- * renders `position: fixed` at `zIndex: 50`, anchored to the viewport and not
- * to its container, so it appears identically whichever region carries it. That
- * is what makes "first declared region holding a content tree" a derivation
- * rather than a guess dressed up as one: there is no better region to prefer.
- *
- * `PAGE_SOURCE_KEY` is the platform's existing name for a flat page's body
- * source — the same convention `decideContentPageFloor` already keys on in the
- * caller. One shared convention, not a per-resource list.
- */
 const PAGE_SOURCE_KEY = "page";
 
 function findContentHost(
@@ -190,36 +232,6 @@ function findContentHost(
 	return puckContentOf(resolved[PAGE_SOURCE_KEY]);
 }
 
-/**
- * Serialise EVERYTHING THIS VIEWER MAY SEE as text for the assistant.
- *
- * BOTH THE RESULT AND THE RENDERED DOCUMENT, BECAUSE NEITHER IS SUFFICIENT.
- * The original serialiser sent the resource record plus the page's content
- * tree, which is exactly right for a proposal — the proposal's substance IS in
- * its blocks. It is wrong for anything the platform GENERATES a document from.
- * A report's body page is a shared template (one `builda_pages` row serves
- * every respondent) so the content tree holds headings and layout and not one
- * personal fact, while the substance — the answers, the category scores, the
- * computed narrative and bands — sits in sibling resolved keys the serialiser
- * never looked at. Sending only the page would give the assistant a form with
- * no answers; sending only the record would leave it unable to discuss what the
- * reader is actually looking at. An assessment result GENERATES a report, so
- * the assistant needs both halves of that.
- *
- * NO KEY IS NAMED, INCLUDED OR EXCLUDED. The loader row decides what a page
- * resolves; this walks whatever that produced. A draft carried a `CHROME_KEYS`
- * exclusion list dropping brand, website, header and footer — every one of them
- * a loader source key, which is to say database facts hardcoded here to save a
- * few hundred tokens of colours and navigation markup. Not a trade worth a
- * literal that goes stale in silence. A loader resolving a new source reaches
- * the assistant with no edit here (`offered-is-derived`).
- *
- * IT CANNOT OUTRUN THE GATE, BY CONSTRUCTION. This runs AFTER every content
- * gate, and a gate withholds by REMOVING content from this same graph. So
- * "everything in the graph" and "everything this viewer may see" are the same
- * set, and they cannot drift — which is what makes serialising the whole graph
- * safe rather than reckless.
- */
 async function buildResourceContext(
 	resolved: Record<string, unknown>,
 	resourceKey: string,