@k2b/cloud 0.36.0 → 0.38.0

package/src/server/help.ts

@@ -1,20 +1,48 @@
+import { formatShortcut } from "@k2b/ui";
 import { Hono } from "hono";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
-import { type HelpDocumentManifest, type HelpDocumentPayload, type HelpSearchPayload, helpLocaleChain } from "../shared/help";
-import { markdownToPlainText, renderHelpMarkdown } from "../shared/markdown";
+import { helpLinkTargets } from "../_internal/help";
+import { helpAgentMarkdown } from "../_internal/help-catalog";
+import {
+  HELP_ACCESS_LEVELS,
+  HELP_KINDS,
+  HELP_REFERENCE_PATTERN,
+  type HelpDocumentManifest,
+  type HelpDocumentPayload,
+  type HelpKind,
+  type HelpSearchPayload,
+  helpLocaleChain,
+  parseHelpReference,
+} from "../shared/help";
+import { helpHtmlToPlainText, lexHelpMarkdown, renderHelpMarkdown, walkHelpTokens } from "../shared/markdown";
 import { auth } from "./middleware/auth";
 
+// A help: target in a Markdown link or definition, an autolink, or an attribute value inside an HTML tag.
+const RAW_HELP_TARGET = /(?:(?:\]\(|\]:)\s*<?|<|<[^>]*\s[\w:-]+\s*=\s*["']?)\s*help:/i;
+
 const metadataSchema = z.object({
   id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
   title: z.string().trim().min(1),
   icon: z.string().trim().min(1).optional(),
   description: z.string().trim().min(1).optional(),
   order: z.number().int().optional(),
+  kind: z.enum(HELP_KINDS).optional(),
+  needs: z.enum(HELP_ACCESS_LEVELS).optional(),
+  next: z
+    .string()
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+    .optional(),
+  related: z
+    .array(z.string().regex(HELP_REFERENCE_PATTERN))
+    .refine((refs) => new Set(refs).size === refs.length, "Duplicate related Help reference")
+    .optional(),
 });
 
-export type HelpDefinitionDocument = Omit<z.infer<typeof metadataSchema>, "order"> & {
+export type HelpDefinitionDocument = Omit<z.infer<typeof metadataSchema>, "order" | "kind" | "related"> & {
   order: number;
+  kind: HelpKind;
+  related: readonly string[];
   markdown: string;
   html: string;
   searchText: string;
@@ -34,7 +62,7 @@ export type HelpCollection = {
   getMarkdown: (id: string) => string | undefined;
 };
 
-type ParsedHelpDocument = Omit<HelpDefinitionDocument, "order"> & { order?: number };
+type ParsedHelpDocument = z.infer<typeof metadataSchema> & Pick<HelpDefinitionDocument, "markdown" | "html" | "searchText">;
 
 const parseSource = (source: string, locale: string): ParsedHelpDocument => {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(source);
@@ -43,12 +71,13 @@ const parseSource = (source: string, locale: string): ParsedHelpDocument => {
   const metadata = metadataSchema.parse(parseYaml(match[1]!));
   const markdown = match[2]!.trim();
   if (!markdown) throw new Error(`Help document "${metadata.id}" has no body`);
+  const html = renderHelpMarkdown(markdown, { locale });
 
   return {
     ...metadata,
     markdown,
-    html: renderHelpMarkdown(markdown, locale),
-    searchText: markdownToPlainText(markdown),
+    html,
+    searchText: helpHtmlToPlainText(html),
   };
 };
 
@@ -69,12 +98,27 @@ const parseDocuments = (
     .map((source) => parseSource(source, locale))
     .map((document): HelpDefinitionDocument => {
       const base = baseById?.get(document.id);
-      if (!baseById) return { ...document, order: document.order ?? 100 };
+      if (!baseById)
+        return { ...document, order: document.order ?? 100, kind: document.kind ?? "task", related: Object.freeze(document.related ?? []) };
       if (!base) throw new Error(`Help locale "${locale}" contains unknown document id "${document.id}"`);
       if ((document.icon !== undefined && document.icon !== base.icon) || (document.order !== undefined && document.order !== base.order)) {
         throw new Error(`Help locale "${locale}" must preserve icon and order for document "${document.id}"`);
       }
-      return { ...document, icon: base.icon, description: document.description ?? base.description, order: base.order };
+      for (const field of ["kind", "needs", "next", "related"] as const) {
+        if (document[field] !== undefined && JSON.stringify(document[field]) !== JSON.stringify(base[field])) {
+          throw new Error(`Help locale "${locale}" must preserve ${field} for document "${document.id}"`);
+        }
+      }
+      return {
+        ...document,
+        icon: base.icon,
+        description: document.description ?? base.description,
+        order: base.order,
+        kind: base.kind,
+        needs: base.needs,
+        next: base.next,
+        related: base.related,
+      };
     })
     .sort((a, b) => a.order - b.order || a.title.localeCompare(b.title))
     .map((document) => Object.freeze(document));
@@ -116,6 +160,82 @@ export const defineHelp = (
     documentsByLocale[locale] = parseDocuments(sources, locale, baseById);
   }
 
+  for (const [locale, localizedDocuments] of Object.entries(documentsByLocale)) {
+    for (const document of localizedDocuments) {
+      const validate = (reference: string, field: string) => {
+        const ref = parseHelpReference(reference);
+        if (!ref || (!ref.appId && !baseById.has(ref.documentId))) {
+          throw new Error(`Help locale "${locale}" document "${document.id}" has unknown ${field} reference "${reference}"`);
+        }
+      };
+      if (document.next === document.id)
+        throw new Error(`Help locale "${locale}" document "${document.id}" must not reference itself in next`);
+      if (document.next) validate(document.next, "next");
+      for (const reference of document.related) validate(reference, "related");
+      const unreadableLink = () =>
+        new Error(
+          `Help document "${document.id}" has a help: link that agents cannot read in locale "${locale}"; write it inline as [text](help:id)`,
+        );
+      const tokens = lexHelpMarkdown(document.markdown, locale);
+      const targets: string[] = [];
+      if (Object.values(tokens.links).some((link) => /^help:/i.test(link.href) && !link.href.startsWith("help:"))) throw unreadableLink();
+      walkHelpTokens(tokens, (token) => {
+        if (
+          (token.type === "link" && /^help:/i.test(token.href) && (!token.href.startsWith("help:") || !token.raw.startsWith("["))) ||
+          (token.type === "image" && /^help:/i.test(token.href)) ||
+          (token.type === "html" && RAW_HELP_TARGET.test(token.raw))
+        )
+          throw unreadableLink();
+        if ((token.type === "paragraph" || token.type === "text") && token.tokens?.length) {
+          let prose = token.raw;
+          // Keep line positions while excluding multiline code spans from the author contract.
+          walkHelpTokens(token.tokens, (child) => {
+            if (child.type === "codespan") prose = prose.replaceAll(child.raw, child.raw.replace(/[^\r\n]/g, "x"));
+          });
+          const block = /^ {0,3}:::(details|steps|reference|compare)(?=[ \t\r]|$)/m.exec(prose);
+          if (block) {
+            const missing =
+              block[1] === "details" ? "a blank line before it, a title, or a closing :::" : "a blank line before it or a closing :::";
+            throw new Error(`Help document "${document.id}" has a :::${block[1]} block without ${missing} in locale "${locale}"`);
+          }
+        }
+        if (token.type === "link" && token.href.startsWith("help:")) {
+          const target = token.href.slice(5);
+          validate(target, "help:");
+          targets.push(target);
+        }
+        // Callouts do not render inside details, and a warning must stay where the reader sees it.
+        if (token.type === "helpDetails" && token.callout === true) {
+          throw new Error(
+            `Help document "${document.id}" has a callout inside details in locale "${locale}"; place it outside the details`,
+          );
+        }
+        if (token.type === "helpKbd" && formatShortcut(String(token.keys), { platform: "other", locale }).keys.length === 0) {
+          throw new Error(`Help document "${document.id}" has an invalid key shortcut "${token.keys}" in locale "${locale}"`);
+        }
+      });
+      // Unconverted Help syntax and targets fail here instead of reaching agents.
+      const agentTokens = lexHelpMarkdown(helpAgentMarkdown({ markdown: document.markdown, locale, appId: "", links: {} }, tokens), locale);
+      let unconvertedLink = Object.values(agentTokens.links).some((link) => link.href.startsWith("help:"));
+      let unconvertedSyntax = false;
+      walkHelpTokens(agentTokens, (token) => {
+        if (
+          (token.type === "link" && token.href.startsWith("help:")) ||
+          // Markdown inside raw HTML and callout titles stays text in agent text, so its target would reach readers.
+          (token.type === "html" && RAW_HELP_TARGET.test(token.raw)) ||
+          (token.type === "markdownInfoBlock" && typeof token.title === "string" && RAW_HELP_TARGET.test(token.title))
+        )
+          unconvertedLink = true;
+        if (token.type === "helpKbd" || token.type === "helpLabel" || token.type === "helpDetails") unconvertedSyntax = true;
+      });
+      if (unconvertedLink) throw unreadableLink();
+      if (unconvertedSyntax) {
+        throw new Error(`Help document "${document.id}" has Help syntax that agents cannot read in locale "${locale}"`);
+      }
+      helpLinkTargets.set(document, targets);
+    }
+  }
+
   return {
     baseLocale,
     documentsByLocale: Object.freeze(documentsByLocale),
@@ -135,6 +255,8 @@ export const defineHelp = (
  * IDs, ordering and ownership stay visible in code; no filesystem scanning or
  * build-time convention is required.
  *
+ * Its payload includes kind and needs, but no next and an empty related list: it has no page route to link to.
+ *
  * @deprecated Declare Help with `defineHelp()` and pass it to `app.start({ help })`. This router only
  * requires sign-in; it does not apply the app's Help visibility, so the mounting app's routes must guard it.
  */
@@ -145,12 +267,13 @@ export const defineHelpCollection = (options: { basePath: string; sources: reado
   const byId = new Map(documents.map((document) => [document.id, document]));
 
   const searchUrl = `${basePath}/search`;
-  const manifest = documents.map<HelpDocumentManifest>(({ id, title, icon, description, order }) => ({
+  const manifest = documents.map<HelpDocumentManifest>(({ id, title, icon, description, order, kind }) => ({
     id,
     title,
     icon,
     description,
     order,
+    kind,
     searchUrl,
     url: `${basePath}/${encodeURIComponent(id)}`,
   }));
@@ -180,8 +303,11 @@ export const defineHelpCollection = (options: { basePath: string; sources: reado
         locale: "en",
         id: document.id,
         title: document.title,
-        markdown: document.markdown,
+        markdown: helpAgentMarkdown({ markdown: document.markdown, locale: "en", appId: "", links: {} }),
         html: document.html,
+        kind: document.kind,
+        needs: document.needs,
+        related: [],
       };
       return context.json(payload);
     });

package/src/server/services/geo.ts

@@ -1,6 +1,13 @@
 import { err, fail, ok, type PageParams, type Paginated, paginate, type Result } from "@k2b/stdlib";
 import { z } from "zod";
 import { readBoundedJson } from "../../_internal/bounded-json";
+import { env } from "../../config/env";
+import { createAllowedNetworkFetch } from "../../services/allowed-network-fetch";
+import { logger } from "../../services/logging";
+import { NetworkTargetBlockedError } from "../../services/network-security";
+import { parseNetworkAllowlistEnv } from "../../shared/network-address";
+
+export const geoAllowlist = () => parseNetworkAllowlistEnv("GEO_ALLOWED_TARGETS", env.GEO_ALLOWED_TARGETS);
 
 const GEO_TIMEOUT_MS = 2_000;
 const GEO_MAX_RESPONSE_BYTES = 256 * 1024;
@@ -118,8 +125,11 @@ const list = async (config: {
   }
 
   try {
-    const res = await fetch(`${baseUrlResult.data}/geo/search?${params}`, { signal: geoSignal(config.signal) });
+    const res = await createAllowedNetworkFetch(geoAllowlist())(`${baseUrlResult.data}/geo/search?${params}`, {
+      signal: geoSignal(config.signal),
+    });
     if (!res.ok) {
+      await res.body?.cancel();
       return unavailable();
     }
 
@@ -152,7 +162,9 @@ const list = async (config: {
       total: filtered.length,
       hasNext: page * perPage < filtered.length,
     });
-  } catch {
+  } catch (error) {
+    if (error instanceof NetworkTargetBlockedError)
+      logger("geo").warn("Geo target is on an internal network. An operator can allow it with GEO_ALLOWED_TARGETS.");
     return unavailable();
   }
 };
@@ -165,8 +177,11 @@ const get = async (config: { baseUrl: string; lat: number; lon: number }): Promi
   if (!baseUrlResult.ok) return baseUrlResult;
 
   try {
-    const res = await fetch(`${baseUrlResult.data}/geo/reverse?lat=${config.lat}&lng=${config.lon}`, { signal: geoSignal() });
+    const res = await createAllowedNetworkFetch(geoAllowlist())(`${baseUrlResult.data}/geo/reverse?lat=${config.lat}&lng=${config.lon}`, {
+      signal: geoSignal(),
+    });
     if (!res.ok) {
+      await res.body?.cancel();
       return unavailable();
     }
 
@@ -181,7 +196,9 @@ const get = async (config: { baseUrl: string; lat: number; lon: number }): Promi
       .find((place): place is GeoPlace => place !== null);
 
     return ok(first ?? null);
-  } catch {
+  } catch (error) {
+    if (error instanceof NetworkTargetBlockedError)
+      logger("geo").warn("Geo target is on an internal network. An operator can allow it with GEO_ALLOWED_TARGETS.");
     return unavailable();
   }
 };

package/src/services/allowed-network-fetch.ts

@@ -0,0 +1,189 @@
+import { type ClientRequest, request as httpRequest, type IncomingMessage, type RequestOptions } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { type NetworkAllowlist, networkAddressFamily, normalizeNetworkHostname } from "../shared/network-address";
+import { type NetworkLookup, pinnedNetworkLookup, resolveAllowedNetworkAddresses } from "./network-security";
+
+type RequestFactory = (options: RequestOptions, callback: (response: IncomingMessage) => void) => ClientRequest;
+type AllowedNetworkFetchDeps = {
+  lookup?: NetworkLookup;
+  resolve?: typeof resolveAllowedNetworkAddresses;
+  request?: RequestFactory;
+};
+
+/**
+ * Fetch-compatible HTTP transport for operator-allowlisted targets. Resolves and
+ * pins every request, without proxies, retries, decompression or its own timeout.
+ * Never follows redirects: `redirect: "error"` rejects any 3xx; otherwise returns
+ * that response unchanged. The caller owns deadlines and response consumption.
+ */
+export const createAllowedNetworkFetch =
+  (allowlist: NetworkAllowlist, deps: AllowedNetworkFetchDeps = {}) =>
+  async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const request = new Request(input, init);
+    const url = new URL(request.url);
+    if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Network target must use HTTP or HTTPS");
+    if (url.username || url.password) throw new TypeError("Network target must not include user information");
+    const signal = request.signal;
+    signal.throwIfAborted();
+    const addresses = await new Promise<Awaited<ReturnType<typeof resolveAllowedNetworkAddresses>>>((resolve, reject) => {
+      const abort = () => reject(signal.reason);
+      signal.addEventListener("abort", abort, { once: true });
+      (deps.resolve ?? resolveAllowedNetworkAddresses)(url.hostname, allowlist, deps.lookup)
+        .then(resolve, reject)
+        .finally(() => signal.removeEventListener("abort", abort));
+      if (signal.aborted) abort();
+    });
+    signal.throwIfAborted();
+    // A body of known size goes out with Content-Length; only a caller's stream (in init or an input Request) is chunked.
+    const streamed = init?.body != null ? init.body instanceof ReadableStream : input instanceof Request && input.body !== null;
+    const payload = request.body && !streamed ? new Uint8Array(await request.arrayBuffer()) : undefined;
+    signal.throwIfAborted();
+    return new Promise<Response>((resolve, reject) => {
+      const headers = new Headers(request.headers);
+      headers.set("host", url.host);
+      headers.set("accept-encoding", "identity");
+      if (payload) headers.set("content-length", String(payload.byteLength));
+      let response: IncomingMessage | undefined;
+      let upload: ReadableStreamDefaultReader<Uint8Array> | undefined;
+      let bodyController: ReadableStreamDefaultController<Uint8Array> | undefined;
+      const cleanup = () => signal.removeEventListener("abort", abort);
+      const fail = (error: Error) => {
+        reject(error);
+        bodyController?.error(error);
+        bodyController = undefined;
+        response?.destroy();
+        void upload?.cancel(error).catch(() => {});
+        outgoing.destroy(error);
+        cleanup();
+      };
+      const abort = () => fail(signal.reason);
+      const outgoing = (deps.request ?? (url.protocol === "https:" ? httpsRequest : httpRequest))(
+        {
+          protocol: url.protocol,
+          hostname: normalizeNetworkHostname(url.hostname),
+          port: url.port || undefined,
+          path: `${url.pathname}${url.search}`,
+          method: request.method,
+          headers: Object.fromEntries(headers),
+          servername: url.protocol === "https:" && !networkAddressFamily(url.hostname) ? normalizeNetworkHostname(url.hostname) : undefined,
+          lookup: pinnedNetworkLookup(addresses),
+          agent: false,
+        } satisfies RequestOptions & { servername?: string },
+        (incoming) => {
+          response = incoming;
+          incoming.once("close", cleanup);
+          incoming.once("error", (error) => {
+            reject(error);
+            bodyController?.error(error);
+            bodyController = undefined;
+          });
+          const status = incoming.statusCode ?? 0;
+          if (request.redirect === "error" && status >= 300 && status < 400) {
+            fail(new TypeError(`Network target returned HTTP ${status} redirect`));
+            return;
+          }
+          const encoding = incoming.headers["content-encoding"];
+          if (encoding && encoding.trim().toLowerCase() !== "identity") {
+            fail(new TypeError("Network target returned an unsupported content encoding"));
+            return;
+          }
+          const responseHeaders = new Headers();
+          for (let i = 0; i < incoming.rawHeaders.length; i += 2)
+            responseHeaders.append(incoming.rawHeaders[i]!, incoming.rawHeaders[i + 1]!);
+          const empty = request.method === "HEAD" || [204, 205, 304].includes(status);
+          const iterator = incoming[Symbol.asyncIterator]();
+          const body = empty
+            ? null
+            : new ReadableStream<Uint8Array>({
+                start(controller) {
+                  bodyController = controller;
+                },
+                async pull(controller) {
+                  try {
+                    const chunk = await iterator.next();
+                    if (!bodyController) return;
+                    if (chunk.done) {
+                      bodyController = undefined;
+                      controller.close();
+                      cleanup();
+                    } else controller.enqueue(new Uint8Array(chunk.value));
+                  } catch (error) {
+                    if (bodyController) {
+                      bodyController = undefined;
+                      controller.error(error);
+                    }
+                    outgoing.destroy();
+                    cleanup();
+                  }
+                },
+                cancel() {
+                  bodyController = undefined;
+                  incoming.destroy();
+                  outgoing.destroy();
+                  cleanup();
+                },
+              });
+          try {
+            resolve(new Response(body, { status, statusText: incoming.statusMessage, headers: responseHeaders }));
+            if (empty) incoming.resume();
+          } catch (error) {
+            fail(error instanceof Error ? error : new Error(String(error)));
+          }
+        },
+      );
+      outgoing.once("close", () => {
+        void upload?.cancel().catch(() => {});
+      });
+      outgoing.once("error", (error) => {
+        reject(error);
+        bodyController?.error(error);
+        bodyController = undefined;
+        response?.destroy();
+        cleanup();
+      });
+      signal.addEventListener("abort", abort, { once: true });
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      if (payload) {
+        outgoing.end(payload);
+        return;
+      }
+      void (async () => {
+        const reader = request.body?.getReader();
+        upload = reader;
+        try {
+          if (reader) {
+            while (true) {
+              const chunk = await reader.read();
+              if (chunk.done) break;
+              if (outgoing.destroyed) break;
+              if (!outgoing.write(chunk.value))
+                await new Promise<void>((resolve, reject) => {
+                  const closed = () => {
+                    clear();
+                    reject(new Error("Request closed"));
+                  };
+                  const drained = () => {
+                    clear();
+                    resolve();
+                  };
+                  const clear = () => {
+                    outgoing.off("close", closed);
+                    outgoing.off("drain", drained);
+                  };
+                  outgoing.once("drain", drained);
+                  outgoing.once("close", closed);
+                });
+            }
+          }
+          outgoing.end();
+        } catch (error) {
+          fail(error instanceof Error ? error : new Error(String(error)));
+        } finally {
+          await reader?.cancel().catch(() => {});
+        }
+      })();
+    });
+  };

package/src/services/help/index.ts

@@ -4,7 +4,8 @@ import { getApp, listApps } from "../../_internal/registry";
 import type { AppRegistryEntry } from "../../contracts/registry";
 import type { RequestActor } from "../../contracts/shared";
 import { resolveAppPresentations } from "../../shared/app-presentation";
-import { helpLocaleChain } from "../../shared/help";
+import { type HelpArticleLink, helpLocaleChain, parseHelpReference } from "../../shared/help";
+import { lexHelpMarkdown, walkHelpTokens } from "../../shared/markdown";
 import { logger } from "../logging";
 import { HELP_RESOURCE_PAGE_SIZE, type HelpSelection, hasHelpBm25, metadata, queryHelp } from "./store";
 import type { HelpReader } from "./types";
@@ -36,9 +37,8 @@ export const createHelpReader = (
 ): HelpReader => {
   const db = dependencies.db ?? sql;
   const visible = (app: AppRegistryEntry | null): app is AppRegistryEntry => app !== null && canReadAppHelp(app, viewer);
-  const select = async (appId?: string): Promise<HelpSelection[]> => {
-    const apps = appId ? [await (dependencies.getApp ?? getApp)(appId)] : await (dependencies.listApps ?? listApps)();
-    return resolveAppPresentations(apps.filter(visible), locale).flatMap((app) =>
+  const selectionFor = (apps: AppRegistryEntry[]): HelpSelection[] =>
+    apps.flatMap((app) =>
       app.help
         ? [
             {
@@ -50,6 +50,9 @@ export const createHelpReader = (
           ]
         : [],
     );
+  const select = async (appId?: string): Promise<HelpSelection[]> => {
+    const apps = appId ? [await (dependencies.getApp ?? getApp)(appId)] : await (dependencies.listApps ?? listApps)();
+    return selectionFor(resolveAppPresentations(apps.filter(visible), locale));
   };
   return {
     async manifest(appId) {
@@ -80,6 +83,7 @@ export const createHelpReader = (
             icon: row.icon ?? undefined,
             description: row.description ?? undefined,
             order: row.sort_order,
+            kind: row.kind,
             locale: row.locale,
             searchUrl: `/api/help/v1/${encodeURIComponent(appId)}/search`,
             url: `/api/help/v1/${encodeURIComponent(appId)}/documents/${encodeURIComponent(row.document_id)}`,
@@ -91,7 +95,44 @@ export const createHelpReader = (
     },
     async read(input) {
       const [row] = await queryHelp(await select(input.appId), { documentId: input.documentId, body: true, limit: 1 }, db);
-      return row?.markdown === undefined ? null : { ...metadata(row), markdown: row.markdown };
+      if (row?.markdown === undefined) return null;
+      const references = new Set<string>();
+      const add = (reference: string) => {
+        const ref = parseHelpReference(reference);
+        if (ref) references.add(`${ref.appId ?? input.appId}/${ref.documentId}`);
+      };
+      if (row.next_id) add(row.next_id);
+      for (const reference of row.related) add(reference);
+      walkHelpTokens(lexHelpMarkdown(row.markdown, row.locale), (token) => {
+        if (token.type === "link" && token.href.startsWith("help:")) add(token.href.slice(5));
+      });
+      // Only targets in the current Help of apps this viewer may see become links; the rest stay text.
+      const referencedApps = new Set([...references].map((reference) => reference.split("/")[0]));
+      const apps = references.size
+        ? resolveAppPresentations(
+            (referencedApps.size === 1 && referencedApps.has(input.appId)
+              ? [await (dependencies.getApp ?? getApp)(input.appId)]
+              : await (dependencies.listApps ?? listApps)()
+            ).filter((app): app is AppRegistryEntry => visible(app) && referencedApps.has(app.id)),
+            locale,
+          )
+        : [];
+      const targets = apps.length ? await queryHelp(selectionFor(apps), { references: [...references] }, db) : [];
+      const accents = new Map(apps.map((app) => [app.id, app.appearance?.accent]));
+      const links: Record<string, HelpArticleLink> = {};
+      for (const target of targets) {
+        links[`${target.app_id}/${target.document_id}`] = {
+          appId: target.app_id,
+          appName: target.app_name,
+          accent: accents.get(target.app_id),
+          documentId: target.document_id,
+          title: target.title,
+          description: target.description ?? undefined,
+          icon: target.icon ?? undefined,
+          url: `/help/apps/${encodeURIComponent(target.app_id)}/${encodeURIComponent(target.document_id)}`,
+        };
+      }
+      return { ...metadata(row), markdown: row.markdown, links };
     },
     async search(input) {
       const query = input.query.trim().slice(0, 200);

package/src/services/help/store.ts

@@ -1,6 +1,7 @@
 import { type SQL, sql } from "bun";
 import { APP_REGISTRY_TTL_MS } from "../../_internal/registry";
-import { ensureSchema } from "../postgres";
+import type { HelpAccessLevel, HelpKind } from "../../shared/help";
+import { ensureSchema, toPgTextArray } from "../postgres";
 import type { HelpCorpus, HelpMetadata } from "./types";
 
 // One expired app lease of grace after an app can no longer be discovered.
@@ -26,6 +27,15 @@ export const migrateHelp = async (db: SQL = sql): Promise<void> => {
     PRIMARY KEY (app_id, manifest_hash, locale, document_id),
     FOREIGN KEY (app_id, manifest_hash) REFERENCES help.corpora ON DELETE CASCADE
   )`.simple();
+    const columns = await tx`SELECT column_name FROM information_schema.columns
+      WHERE table_schema = 'help' AND table_name = 'documents'
+        AND column_name IN ('kind', 'needs', 'next_id', 'related')`;
+    if (columns.length < 4)
+      await tx`ALTER TABLE help.documents
+      ADD COLUMN IF NOT EXISTS kind text NOT NULL DEFAULT 'task',
+      ADD COLUMN IF NOT EXISTS needs text,
+      ADD COLUMN IF NOT EXISTS next_id text,
+      ADD COLUMN IF NOT EXISTS related text[] NOT NULL DEFAULT '{}'`.simple();
     await tx`CREATE INDEX IF NOT EXISTS help_search_idx ON help.documents USING gin(search_document)`.simple();
   });
   // The operator enables the extension; Help never installs server extensions.
@@ -63,9 +73,9 @@ export const registerHelp = async (corpus: HelpCorpus, db: SQL = sql): Promise<v
       for (const document of documents) {
         const text = `${document.title}\n${document.description ?? ""}\n${document.searchText}`;
         await tx`INSERT INTO help.documents(app_id, manifest_hash, locale, document_id, title, description, icon,
-          sort_order, markdown, search_text, search_config, search_document)
+          sort_order, kind, needs, next_id, related, markdown, search_text, search_config, search_document)
           VALUES (${corpus.appId}, ${corpus.manifestHash}, ${locale}, ${document.id}, ${document.title},
-            ${document.description ?? null}, ${document.icon ?? null}, ${document.order}, ${document.markdown}, ${text}, ${config},
+            ${document.description ?? null}, ${document.icon ?? null}, ${document.order}, ${document.kind}, ${document.needs ?? null}, ${document.next ?? null}, ${toPgTextArray([...document.related])}::text[], ${document.markdown}, ${text}, ${config},
             setweight(to_tsvector(${config}::regconfig, ${document.id + " " + document.title}), 'A') ||
             setweight(to_tsvector(${config}::regconfig, ${document.description ?? ""}), 'B') ||
             setweight(to_tsvector(${config}::regconfig, ${document.searchText}), 'D'))`;
@@ -97,6 +107,10 @@ type Row = {
   description: string | null;
   icon: string | null;
   sort_order: number;
+  kind: HelpKind;
+  needs: HelpAccessLevel | null;
+  next_id: string | null;
+  related: string[];
   markdown?: string;
 };
 export const metadata = (row: Row): HelpMetadata => ({
@@ -109,6 +123,10 @@ export const metadata = (row: Row): HelpMetadata => ({
   description: row.description ?? undefined,
   icon: row.icon ?? undefined,
   order: row.sort_order,
+  kind: row.kind,
+  needs: row.needs ?? undefined,
+  next: row.next_id ?? undefined,
+  related: row.related,
 });
 
 export const hasHelpBm25 = async (db: SQL = sql): Promise<boolean> => {
@@ -130,6 +148,7 @@ export const queryHelp = async (
     limit?: number;
     cursor?: string;
     bm25?: boolean;
+    references?: readonly string[];
   },
   db: SQL = sql,
 ): Promise<Row[]> => {
@@ -145,10 +164,11 @@ export const queryHelp = async (
   const pending = db.unsafe<Row[]>(
     `WITH active AS (
     SELECT * FROM jsonb_to_recordset(($1::text)::jsonb) AS a(app_id text, app_name text, manifest_hash text, locales text[])
-  ) SELECT d.app_id, a.app_name, d.manifest_hash, d.locale, d.document_id, d.title, d.description, d.icon, d.sort_order
+  ) SELECT d.app_id, a.app_name, d.manifest_hash, d.locale, d.document_id, d.title, d.description, d.icon, d.sort_order, d.kind, d.needs, d.next_id, d.related
     ${input.body ? ", d.markdown" : ""}
     FROM help.documents d JOIN active a ON a.app_id=d.app_id AND a.manifest_hash=d.manifest_hash
     WHERE length($2::text) >= 0 AND d.locale=ANY(a.locales)
+      AND ($5::text[] IS NULL OR (d.app_id || '/' || d.document_id)=ANY($5::text[]))
       AND NOT EXISTS (SELECT 1 FROM help.documents preferred
         WHERE preferred.app_id=d.app_id AND preferred.manifest_hash=d.manifest_hash AND preferred.document_id=d.document_id
           AND preferred.locale=ANY(a.locales) AND array_position(a.locales, preferred.locale)<array_position(a.locales, d.locale))
@@ -162,12 +182,13 @@ export const queryHelp = async (
         : ""
     }
       d.app_id COLLATE "C", ${input.cursor !== undefined ? "" : "d.sort_order,"} d.document_id COLLATE "C"
-    ${input.limit !== undefined ? "LIMIT $5" : ""}`,
+    ${input.limit !== undefined ? "LIMIT $6" : ""}`,
     [
       JSON.stringify(selection),
       input.query ?? "",
       input.documentId ?? null,
       input.cursor ?? null,
+      input.references ? toPgTextArray([...input.references]) : null,
       ...(input.limit !== undefined ? [input.limit] : []),
     ],
   );