@wildo-ai/saas-technical-doc 1.1.1 → 1.1.2

package/dist/esm/companion/application-documentation/application-connection-documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-connection-documentation.js","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-connection-documentation.ts"],"names":[],"mappings":"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","sourcesContent":["import { MAIN_API_BASE_PATH, MANUAL_CONTROLLER_ROUTES_URLS, ManualControllerRouteKey } from '@wildo-ai/saas-models';\n\n/**\n * The application's own name and the addresses an integrator connects to.\n *\n * Engine documentation is written once for every generated application, so it\n * used to hedge everything an application knows about itself: \"the server origin\n * from this application's API reference\", \"the address published for this\n * environment\", \"the application\". Every one of those values is available to the\n * companion at derivation time, and this projection is how they reach the page.\n *\n * The split is deliberate. The APPLICATION supplies what only it knows — its\n * customer-facing name and the base URLs it publishes. The ENGINE supplies the\n * paths, because a route is the engine's own contract and an application that\n * restated it would hold a second copy that can drift (see\n * `MANUAL_CONTROLLER_ROUTES_URLS`, whose values are mounted under\n * `MAIN_API_BASE_PATH`). An endpoint appears only when the companion has\n * observed that the application configures that surface, so a page never\n * advertises a door this application does not open.\n */\nexport const APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-connection' as const;\nexport const APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_VERSION = 1;\n\n/** One base URL an application publishes for an environment a reader may call. */\nexport interface ApplicationConnectionServer {\n  readonly url: string;\n  readonly description?: string;\n}\n\n/**\n * What the companion measures about this application. `surfaces` mirrors the\n * evidence the derivation already computes for applicability gating: the same\n * observation that decides whether the MCP pages are published decides whether\n * the MCP endpoint is printed, so a published address and a published page can\n * never disagree.\n */\nexport interface ApplicationConnectionDocumentationSource {\n  /** The name customers see. The application's `displayName`, else its `appName`. */\n  readonly applicationName: string;\n  /** Base URLs the application publishes, in the order it authored them. Possibly empty. */\n  readonly apiServers: readonly ApplicationConnectionServer[];\n  readonly surfaces: {\n    readonly mcpToolServer: boolean;\n    readonly a2aAgent: boolean;\n  };\n}\n\n/** Named presentations a page may request with `{{APPLICATION_CONNECTION:<selector>}}`. */\nexport enum ApplicationConnectionPresentation {\n  /** Every connection detail as one table: base URLs, the API mount, agent endpoints. */\n  CONNECTION_DETAILS = 'connectionDetails',\n  /** The base URLs alone, for a page that only needs to say where requests go. */\n  BASE_URLS = 'baseUrls',\n  /**\n   * The MCP endpoint sentence. Never empty: an application that exposes no MCP surface gets a\n   * sentence saying so. Projection runs for every unit and gating happens afterwards, so a\n   * presentation that rendered nothing would leave a blank where a suppressed page's prose was,\n   * and would say nothing at all if the page were ever published without its gate.\n   */\n  MCP_ENDPOINT = 'mcpEndpoint',\n  /** The A2A agent-card sentence. Never empty, for the same reason as the MCP endpoint. */\n  A2A_AGENT_CARD = 'a2aAgentCard',\n}\n\n/**\n * Values a page substitutes INSIDE a sample — a JSON client configuration, an HTTP request line —\n * where a block presentation cannot go. Each is a single string, never markdown.\n */\nexport enum ApplicationConnectionInlineValue {\n  /** The first base URL the application publishes, or an explicit stand-in when it publishes none. */\n  BASE_URL = 'baseUrl',\n  /** The full MCP endpoint URL a client configures. */\n  MCP_ENDPOINT_URL = 'mcpEndpointUrl',\n  /** The full agent-card URL an A2A peer fetches. */\n  AGENT_CARD_URL = 'agentCardUrl',\n  /** The full A2A task endpoint URL. */\n  AGENT_TASK_URL = 'agentTaskUrl',\n}\n\nexport interface ApplicationConnectionDocumentationFact {\n  readonly sourceRef: string;\n  readonly sourceVersion: number;\n  /** Substituted wherever a page writes the inline application-name token. */\n  readonly applicationName: string;\n  readonly presentations: Readonly<Record<ApplicationConnectionPresentation, string>>;\n  readonly inlineValues: Readonly<Record<ApplicationConnectionInlineValue, string>>;\n}\n\n/** A manual route as a reader must call it: the mount plus the engine-owned path segment. */\nfunction publicRoutePath(routeKey: ManualControllerRouteKey): string {\n  return `${MAIN_API_BASE_PATH}${MANUAL_CONTROLLER_ROUTES_URLS[routeKey]}`;\n}\n\nfunction baseUrlsMarkdown(source: ApplicationConnectionDocumentationSource): string {\n  if (source.apiServers.length === 0) {\n    // Honest rather than invented: an application that publishes no base URL cannot have one\n    // printed for it, and the reader is told where the answer actually lives.\n    return `${source.applicationName} does not publish its base URLs in this documentation. Read them from the **Servers** list at the top of the API reference, or ask whoever operates the environment you are calling.`;\n  }\n  const rows = source.apiServers\n    .map((server) => `| \\`${server.url}\\` | ${server.description ?? 'Published base URL'} |`)\n    .join('\\n');\n  return `| Base URL | Environment |\\n| --- | --- |\\n${rows}`;\n}\n\nfunction mcpEndpointMarkdown(source: ApplicationConnectionDocumentationSource): string {\n  if (!source.surfaces.mcpToolServer) return `${source.applicationName} does not publish a Model Context Protocol endpoint.`;\n  return `${source.applicationName} serves its Model Context Protocol endpoint at \\`${publicRoutePath(ManualControllerRouteKey.MCP_ENDPOINT)}\\`, under the base URL of the environment you are connecting to.`;\n}\n\nfunction a2aAgentCardMarkdown(source: ApplicationConnectionDocumentationSource): string {\n  if (!source.surfaces.a2aAgent) return `${source.applicationName} does not publish an agent card.`;\n  return `${source.applicationName} publishes its agent card at \\`${publicRoutePath(ManualControllerRouteKey.A2A_AGENT_CARD)}\\` and accepts task calls at \\`${publicRoutePath(ManualControllerRouteKey.A2A_TASKS)}\\`, under the base URL of the environment you are connecting to.`;\n}\n\nfunction connectionDetailsMarkdown(source: ApplicationConnectionDocumentationSource): string {\n  const rows: string[] = [];\n  for (const server of source.apiServers) {\n    rows.push(`| Base URL${server.description === undefined ? '' : ` (${server.description})`} | \\`${server.url}\\` |`);\n  }\n  rows.push(`| API mount | \\`${MAIN_API_BASE_PATH}\\` — every path in the API reference already includes it |`);\n  if (source.surfaces.mcpToolServer) {\n    rows.push(`| MCP endpoint | \\`${publicRoutePath(ManualControllerRouteKey.MCP_ENDPOINT)}\\` |`);\n  }\n  if (source.surfaces.a2aAgent) {\n    rows.push(`| A2A agent card | \\`${publicRoutePath(ManualControllerRouteKey.A2A_AGENT_CARD)}\\` |`);\n    rows.push(`| A2A task endpoint | \\`${publicRoutePath(ManualControllerRouteKey.A2A_TASKS)}\\` |`);\n  }\n  const table = `| What | Value |\\n| --- | --- |\\n${rows.join('\\n')}`;\n  return source.apiServers.length > 0\n    ? table\n    : `${table}\\n\\nThis application publishes no base URL here; read it from the **Servers** list at the top of the API reference.`;\n}\n\n/**\n * The origin a sample should show. An application that publishes no base URL gets an explicit\n * stand-in rather than a fabricated host: the reader must substitute their own environment, and the\n * sample says so in the place where the value belongs.\n */\nfunction primaryBaseUrl(source: ApplicationConnectionDocumentationSource): string {\n  const first = source.apiServers[0];\n  return first === undefined ? 'https://your-environment.example' : first.url.replace(/\\/+$/, '');\n}\n\n/**\n * Projects the application's connection facts into the presentations a page may\n * request. Every presentation is a pure function of the source, so two runs over\n * the same application produce identical bytes.\n */\nexport function projectApplicationConnectionDocumentation(\n  source: ApplicationConnectionDocumentationSource,\n): ApplicationConnectionDocumentationFact {\n  const applicationName = source.applicationName.trim();\n  if (applicationName.length === 0) throw new Error('application connection projection requires a customer-facing application name');\n  for (const server of source.apiServers) {\n    if (server.url.trim().length === 0) throw new Error('application connection projection received an empty base URL');\n  }\n  const named: ApplicationConnectionDocumentationSource = { ...source, applicationName };\n  return {\n    sourceRef: APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_REF,\n    sourceVersion: APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_VERSION,\n    applicationName,\n    presentations: Object.freeze({\n      [ApplicationConnectionPresentation.CONNECTION_DETAILS]: connectionDetailsMarkdown(named),\n      [ApplicationConnectionPresentation.BASE_URLS]: baseUrlsMarkdown(named),\n      [ApplicationConnectionPresentation.MCP_ENDPOINT]: mcpEndpointMarkdown(named),\n      [ApplicationConnectionPresentation.A2A_AGENT_CARD]: a2aAgentCardMarkdown(named),\n    }),\n    inlineValues: Object.freeze({\n      [ApplicationConnectionInlineValue.BASE_URL]: primaryBaseUrl(named),\n      [ApplicationConnectionInlineValue.MCP_ENDPOINT_URL]: `${primaryBaseUrl(named)}${publicRoutePath(ManualControllerRouteKey.MCP_ENDPOINT)}`,\n      [ApplicationConnectionInlineValue.AGENT_CARD_URL]: `${primaryBaseUrl(named)}${publicRoutePath(ManualControllerRouteKey.A2A_AGENT_CARD)}`,\n      [ApplicationConnectionInlineValue.AGENT_TASK_URL]: `${primaryBaseUrl(named)}${publicRoutePath(ManualControllerRouteKey.A2A_TASKS)}`,\n    }),\n  };\n}\n"]}

package/dist/esm/companion/application-documentation/application-integration-documentation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The tools an MCP client will find, and the events a webhook receiver will be sent.
+ *
+ * Five webhook pages explained delivery, verification, retries and reconciliation without ever
+ * naming an event, and the MCP page described a catalogue without naming a tool in it. Both
+ * inventories were already being computed — as booleans, to decide whether those pages publish at
+ * all — so the reader was one projection away from the list the whole time.
+ *
+ * Names are the application's own: a tool is `<resource>__<operation>` exactly as an agent must
+ * type it, and an event names the resource and operation that produce it. Nothing here is
+ * humanized, because every one of these strings is a value someone matches on in code.
+ */
+export declare const APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_REF: "source:companion-projection:application-integration";
+export declare const APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_VERSION = 1;
+export interface ApplicationMcpToolSource {
+    /** The exact name an agent calls, `<resource>__<operation>`. */
+    readonly toolName: string;
+    readonly resourceIdentifier: string;
+    readonly operationIdentifier: string;
+}
+export interface ApplicationWebhookEventSource {
+    readonly resourceIdentifier: string;
+    readonly operationIdentifier: string;
+    /** The notification channel that carries it, which is also its delivery scope. */
+    readonly channel: string;
+}
+export interface ApplicationIntegrationDocumentationSource {
+    readonly mcpTools: readonly ApplicationMcpToolSource[];
+    readonly webhookEvents: readonly ApplicationWebhookEventSource[];
+}
+/** Named presentations a page may request with `{{APPLICATION_INTEGRATION:<selector>}}`. */
+export declare enum ApplicationIntegrationPresentation {
+    /** Every tool this application publishes to MCP clients. */
+    MCP_TOOLS = "mcpTools",
+    /** Every resource operation that produces an outbound webhook delivery. */
+    WEBHOOK_EVENTS = "webhookEvents"
+}
+export interface ApplicationIntegrationDocumentationFact {
+    readonly sourceRef: string;
+    readonly sourceVersion: number;
+    readonly presentations: Readonly<Record<ApplicationIntegrationPresentation, string>>;
+}
+/**
+ * Projects both integration inventories. A pure function of the source, so two runs over the same
+ * application produce identical bytes.
+ */
+export declare function projectApplicationIntegrationDocumentation(source: ApplicationIntegrationDocumentationSource): ApplicationIntegrationDocumentationFact;
+//# sourceMappingURL=application-integration-documentation.d.ts.map

package/dist/esm/companion/application-documentation/application-integration-documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-integration-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-integration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gDAAgD,EAAG,qDAA8D,CAAC;AAC/H,eAAO,MAAM,oDAAoD,IAAI,CAAC;AAEtE,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,yCAAyC;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACvD,QAAQ,CAAC,aAAa,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAClE;AAED,4FAA4F;AAC5F,oBAAY,kCAAkC;IAC5C,4DAA4D;IAC5D,SAAS,aAAa;IACtB,2EAA2E;IAC3E,cAAc,kBAAkB;CACjC;AAED,MAAM,WAAW,uCAAuC;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,kCAAkC,EAAE,MAAM,CAAC,CAAC,CAAC;CACtF;AAsBD;;;GAGG;AACH,wBAAgB,0CAA0C,CACxD,MAAM,EAAE,yCAAyC,GAChD,uCAAuC,CAezC"}

package/dist/esm/companion/application-documentation/application-integration-documentation.js

@@ -0,0 +1,63 @@
+/**
+ * The tools an MCP client will find, and the events a webhook receiver will be sent.
+ *
+ * Five webhook pages explained delivery, verification, retries and reconciliation without ever
+ * naming an event, and the MCP page described a catalogue without naming a tool in it. Both
+ * inventories were already being computed — as booleans, to decide whether those pages publish at
+ * all — so the reader was one projection away from the list the whole time.
+ *
+ * Names are the application's own: a tool is `<resource>__<operation>` exactly as an agent must
+ * type it, and an event names the resource and operation that produce it. Nothing here is
+ * humanized, because every one of these strings is a value someone matches on in code.
+ */
+export const APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-integration';
+export const APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_VERSION = 1;
+/** Named presentations a page may request with `{{APPLICATION_INTEGRATION:<selector>}}`. */
+export var ApplicationIntegrationPresentation;
+(function (ApplicationIntegrationPresentation) {
+    /** Every tool this application publishes to MCP clients. */
+    ApplicationIntegrationPresentation["MCP_TOOLS"] = "mcpTools";
+    /** Every resource operation that produces an outbound webhook delivery. */
+    ApplicationIntegrationPresentation["WEBHOOK_EVENTS"] = "webhookEvents";
+})(ApplicationIntegrationPresentation || (ApplicationIntegrationPresentation = {}));
+function mcpToolsMarkdown(source) {
+    if (source.mcpTools.length === 0) {
+        return 'This application publishes no MCP tools, so a connected client will find an empty catalogue.';
+    }
+    const rows = source.mcpTools
+        .map((tool) => `| \`${tool.toolName}\` | ${tool.resourceIdentifier} | ${tool.operationIdentifier} |`)
+        .join('\n');
+    return `| Tool | Resource | Operation |\n| --- | --- | --- |\n${rows}\n\nThese are the tools the application publishes. What YOU see is the subset your credential is allowed to call, so a shorter catalogue is an authorization result and not a fault. The API reference carries each operation's exact arguments and response.`;
+}
+function webhookEventsMarkdown(source) {
+    if (source.webhookEvents.length === 0) {
+        return 'This application declares no outbound webhook events, so an endpoint would receive nothing even when one is configured and enabled.';
+    }
+    const rows = source.webhookEvents
+        .map((event) => `| ${event.resourceIdentifier} | ${event.operationIdentifier} | \`${event.channel}\` |`)
+        .join('\n');
+    return `| Resource | Operation that fires it | Channel |\n| --- | --- | --- |\n${rows}\n\nEvery enabled endpoint on the matching channel receives every event on that channel: an endpoint is not subscribed to a subset. Route on the signed \`resourceIdentifier\` and \`operationIdentifier\` claims rather than on the destination URL, and ignore an event your receiver does not handle.`;
+}
+/**
+ * Projects both integration inventories. A pure function of the source, so two runs over the same
+ * application produce identical bytes.
+ */
+export function projectApplicationIntegrationDocumentation(source) {
+    for (const tool of source.mcpTools) {
+        if (tool.toolName.trim().length === 0)
+            throw new Error('application integration projection received an MCP tool with no name');
+    }
+    for (const event of source.webhookEvents) {
+        if (event.channel.trim().length === 0)
+            throw new Error('application integration projection received a webhook event with no channel');
+    }
+    return {
+        sourceRef: APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_REF,
+        sourceVersion: APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_VERSION,
+        presentations: Object.freeze({
+            [ApplicationIntegrationPresentation.MCP_TOOLS]: mcpToolsMarkdown(source),
+            [ApplicationIntegrationPresentation.WEBHOOK_EVENTS]: webhookEventsMarkdown(source),
+        }),
+    };
+}
+//# sourceMappingURL=application-integration-documentation.js.map

package/dist/esm/companion/application-documentation/application-integration-documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-integration-documentation.js","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-integration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gDAAgD,GAAG,qDAA8D,CAAC;AAC/H,MAAM,CAAC,MAAM,oDAAoD,GAAG,CAAC,CAAC;AAqBtE,4FAA4F;AAC5F,MAAM,CAAN,IAAY,kCAKX;AALD,WAAY,kCAAkC;IAC5C,4DAA4D;IAC5D,4DAAsB,CAAA;IACtB,2EAA2E;IAC3E,sEAAgC,CAAA;AAClC,CAAC,EALW,kCAAkC,KAAlC,kCAAkC,QAK7C;AAQD,SAAS,gBAAgB,CAAC,MAAiD;IACzE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,8FAA8F,CAAC;IACxG,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ;SACzB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,CAAC,QAAQ,QAAQ,IAAI,CAAC,kBAAkB,MAAM,IAAI,CAAC,mBAAmB,IAAI,CAAC;SACpG,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,yDAAyD,IAAI,+PAA+P,CAAC;AACtU,CAAC;AAED,SAAS,qBAAqB,CAAC,MAAiD;IAC9E,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO,qIAAqI,CAAC;IAC/I,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa;SAC9B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,kBAAkB,MAAM,KAAK,CAAC,mBAAmB,QAAQ,KAAK,CAAC,OAAO,MAAM,CAAC;SACvG,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,0EAA0E,IAAI,0SAA0S,CAAC;AAClY,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0CAA0C,CACxD,MAAiD;IAEjD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IACjI,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QACzC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;IACxI,CAAC;IACD,OAAO;QACL,SAAS,EAAE,gDAAgD;QAC3D,aAAa,EAAE,oDAAoD;QACnE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC;YAC3B,CAAC,kCAAkC,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC;YACxE,CAAC,kCAAkC,CAAC,cAAc,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC;SACnF,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The tools an MCP client will find, and the events a webhook receiver will be sent.\n *\n * Five webhook pages explained delivery, verification, retries and reconciliation without ever\n * naming an event, and the MCP page described a catalogue without naming a tool in it. Both\n * inventories were already being computed — as booleans, to decide whether those pages publish at\n * all — so the reader was one projection away from the list the whole time.\n *\n * Names are the application's own: a tool is `<resource>__<operation>` exactly as an agent must\n * type it, and an event names the resource and operation that produce it. Nothing here is\n * humanized, because every one of these strings is a value someone matches on in code.\n */\nexport const APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-integration' as const;\nexport const APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_VERSION = 1;\n\nexport interface ApplicationMcpToolSource {\n  /** The exact name an agent calls, `<resource>__<operation>`. */\n  readonly toolName: string;\n  readonly resourceIdentifier: string;\n  readonly operationIdentifier: string;\n}\n\nexport interface ApplicationWebhookEventSource {\n  readonly resourceIdentifier: string;\n  readonly operationIdentifier: string;\n  /** The notification channel that carries it, which is also its delivery scope. */\n  readonly channel: string;\n}\n\nexport interface ApplicationIntegrationDocumentationSource {\n  readonly mcpTools: readonly ApplicationMcpToolSource[];\n  readonly webhookEvents: readonly ApplicationWebhookEventSource[];\n}\n\n/** Named presentations a page may request with `{{APPLICATION_INTEGRATION:<selector>}}`. */\nexport enum ApplicationIntegrationPresentation {\n  /** Every tool this application publishes to MCP clients. */\n  MCP_TOOLS = 'mcpTools',\n  /** Every resource operation that produces an outbound webhook delivery. */\n  WEBHOOK_EVENTS = 'webhookEvents',\n}\n\nexport interface ApplicationIntegrationDocumentationFact {\n  readonly sourceRef: string;\n  readonly sourceVersion: number;\n  readonly presentations: Readonly<Record<ApplicationIntegrationPresentation, string>>;\n}\n\nfunction mcpToolsMarkdown(source: ApplicationIntegrationDocumentationSource): string {\n  if (source.mcpTools.length === 0) {\n    return 'This application publishes no MCP tools, so a connected client will find an empty catalogue.';\n  }\n  const rows = source.mcpTools\n    .map((tool) => `| \\`${tool.toolName}\\` | ${tool.resourceIdentifier} | ${tool.operationIdentifier} |`)\n    .join('\\n');\n  return `| Tool | Resource | Operation |\\n| --- | --- | --- |\\n${rows}\\n\\nThese are the tools the application publishes. What YOU see is the subset your credential is allowed to call, so a shorter catalogue is an authorization result and not a fault. The API reference carries each operation's exact arguments and response.`;\n}\n\nfunction webhookEventsMarkdown(source: ApplicationIntegrationDocumentationSource): string {\n  if (source.webhookEvents.length === 0) {\n    return 'This application declares no outbound webhook events, so an endpoint would receive nothing even when one is configured and enabled.';\n  }\n  const rows = source.webhookEvents\n    .map((event) => `| ${event.resourceIdentifier} | ${event.operationIdentifier} | \\`${event.channel}\\` |`)\n    .join('\\n');\n  return `| Resource | Operation that fires it | Channel |\\n| --- | --- | --- |\\n${rows}\\n\\nEvery enabled endpoint on the matching channel receives every event on that channel: an endpoint is not subscribed to a subset. Route on the signed \\`resourceIdentifier\\` and \\`operationIdentifier\\` claims rather than on the destination URL, and ignore an event your receiver does not handle.`;\n}\n\n/**\n * Projects both integration inventories. A pure function of the source, so two runs over the same\n * application produce identical bytes.\n */\nexport function projectApplicationIntegrationDocumentation(\n  source: ApplicationIntegrationDocumentationSource,\n): ApplicationIntegrationDocumentationFact {\n  for (const tool of source.mcpTools) {\n    if (tool.toolName.trim().length === 0) throw new Error('application integration projection received an MCP tool with no name');\n  }\n  for (const event of source.webhookEvents) {\n    if (event.channel.trim().length === 0) throw new Error('application integration projection received a webhook event with no channel');\n  }\n  return {\n    sourceRef: APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_REF,\n    sourceVersion: APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_VERSION,\n    presentations: Object.freeze({\n      [ApplicationIntegrationPresentation.MCP_TOOLS]: mcpToolsMarkdown(source),\n      [ApplicationIntegrationPresentation.WEBHOOK_EVENTS]: webhookEventsMarkdown(source),\n    }),\n  };\n}\n"]}

package/dist/esm/companion/application-documentation/technical-documentation-engine-content-bundle.d.ts

@@ -1,3 +1,7 @@
+import { type ApplicationConnectionDocumentationFact } from './application-connection-documentation';
+import { type ApplicationAuthenticationDocumentationFact } from './application-authentication-documentation';
+import { type ApplicationIntegrationDocumentationFact } from './application-integration-documentation';
+import { type ApplicationAdministrationDocumentationFact } from './application-administration-documentation';
 import { TechnicalDocumentationAccessClass, TechnicalDocumentationReaderAudience, TechnicalDocumentationUnitKind, type TechnicalDocumentationApplicabilityRequirementV1, type TechnicalDocumentationApiReferenceTargetV1, type TechnicalDocumentationUnitV1 } from '@wildo-ai/saas-specifications/technical-documentation';
 import { type EngineDocumentationSpecificationCatalogV1 } from '@wildo-ai/saas-specifications/companion';
 import type { LoadedApplicationConsumerDocumentationContentBundleV1 } from '../content/application-consumer-documentation-content-loader';
@@ -30,8 +34,22 @@ export interface ApplicationOrganizationRolesDocumentationFact {
  */
 export declare const ENGINE_CONTENT_UNIT_DEFINITIONS: Readonly<Record<string, EngineContentUnitDefinition>>;
 /**
- * Compiles verified engine content and the two explicit application facts
- * (organization roles and unit-aware resources) into private documentation.
+ * The facts only the application knows, which the companion measures and passes in.
+ *
+ * A record rather than a positional list: each is optional because a page declares what it uses,
+ * and the set grows as the documentation learns to say more about the application it ships with.
+ */
+export interface ApplicationDocumentationFacts {
+    readonly organizationRoles?: ApplicationOrganizationRolesDocumentationFact;
+    readonly organizationUnitResources?: ApplicationOrganizationUnitResourcesDocumentationFact;
+    readonly connection?: ApplicationConnectionDocumentationFact;
+    readonly authentication?: ApplicationAuthenticationDocumentationFact;
+    readonly administration?: ApplicationAdministrationDocumentationFact;
+    readonly integration?: ApplicationIntegrationDocumentationFact;
+}
+/**
+ * Compiles verified engine content and the application's own facts (organization roles,
+ * unit-aware resources, name and connection details) into private documentation.
  */
-export declare function projectEngineApplicationConsumerContentBundle(bundle: LoadedApplicationConsumerDocumentationContentBundleV1, engineSpecificationCatalog: EngineDocumentationSpecificationCatalogV1, unitDefinitions?: Readonly<Record<string, EngineContentUnitDefinition>>, applicationOrganizationRolesFact?: ApplicationOrganizationRolesDocumentationFact, applicationOrganizationUnitResourcesFact?: ApplicationOrganizationUnitResourcesDocumentationFact): TechnicalDocumentationUnitV1[];
+export declare function projectEngineApplicationConsumerContentBundle(bundle: LoadedApplicationConsumerDocumentationContentBundleV1, engineSpecificationCatalog: EngineDocumentationSpecificationCatalogV1, unitDefinitions?: Readonly<Record<string, EngineContentUnitDefinition>>, applicationFacts?: ApplicationDocumentationFacts): TechnicalDocumentationUnitV1[];
 //# sourceMappingURL=technical-documentation-engine-content-bundle.d.ts.map

package/dist/esm/companion/application-documentation/technical-documentation-engine-content-bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"technical-documentation-engine-content-bundle.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/technical-documentation-engine-content-bundle.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iCAAiC,EAQjC,oCAAoC,EAGpC,8BAA8B,EAE9B,KAAK,gDAAgD,EACrD,KAAK,0CAA0C,EAG/C,KAAK,4BAA4B,EAClC,MAAM,uDAAuD,CAAC;AAC/D,OAAO,EAGL,KAAK,yCAAyC,EAC/C,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,qDAAqD,EAAE,MAAM,8DAA8D,CAAC;AAC1I,OAAO,EACL,qEAAqE,EAGtE,MAAM,2EAA2E,CAAC;AAEnF,OAAO,EAEL,KAAK,qDAAqD,EAC3D,MAAM,wDAAwD,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;IAC9C,QAAQ,CAAC,eAAe,EAAE,SAAS,oCAAoC,EAAE,CAAC;IAC1E,QAAQ,CAAC,WAAW,EAAE,iCAAiC,CAAC;IACxD,QAAQ,CAAC,yBAAyB,EAAE,SAAS,gDAAgD,EAAE,CAAC;IAChG,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,0CAA0C,CAAA;KAAE,EAAE,CAAC;CACnI;AAwDD,sFAAsF;AACtF,MAAM,WAAW,6CAA6C;IAC5D,QAAQ,CAAC,SAAS,EAAE,GAAG,OAAO,qEAAqE,GAAG,MAAM,EAAE,CAAC;IAC/G,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAoFD;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CA26ChG,CAAC;AAsOH;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,qDAAqD,EAC7D,0BAA0B,EAAE,yCAAyC,EACrE,eAAe,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAmC,EACxG,gCAAgC,CAAC,EAAE,6CAA6C,EAChF,wCAAwC,CAAC,EAAE,qDAAqD,GAC/F,4BAA4B,EAAE,CAmGhC"}
+{"version":3,"file":"technical-documentation-engine-content-bundle.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/technical-documentation-engine-content-bundle.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,sCAAsC,EAC5C,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAGL,KAAK,0CAA0C,EAChD,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAGL,KAAK,uCAAuC,EAC7C,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAGL,KAAK,0CAA0C,EAChD,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAEL,iCAAiC,EAQjC,oCAAoC,EAGpC,8BAA8B,EAE9B,KAAK,gDAAgD,EACrD,KAAK,0CAA0C,EAG/C,KAAK,4BAA4B,EAClC,MAAM,uDAAuD,CAAC;AAC/D,OAAO,EAGL,KAAK,yCAAyC,EAC/C,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,qDAAqD,EAAE,MAAM,8DAA8D,CAAC;AAC1I,OAAO,EACL,qEAAqE,EAGtE,MAAM,2EAA2E,CAAC;AAEnF,OAAO,EAEL,KAAK,qDAAqD,EAC3D,MAAM,wDAAwD,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;IAC9C,QAAQ,CAAC,eAAe,EAAE,SAAS,oCAAoC,EAAE,CAAC;IAC1E,QAAQ,CAAC,WAAW,EAAE,iCAAiC,CAAC;IACxD,QAAQ,CAAC,yBAAyB,EAAE,SAAS,gDAAgD,EAAE,CAAC;IAChG,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,0CAA0C,CAAA;KAAE,EAAE,CAAC;CACnI;AAsED,sFAAsF;AACtF,MAAM,WAAW,6CAA6C;IAC5D,QAAQ,CAAC,SAAS,EAAE,GAAG,OAAO,qEAAqE,GAAG,MAAM,EAAE,CAAC;IAC/G,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAoFD;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAm8ChG,CAAC;AAwWH;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,6CAA6C,CAAC;IAC3E,QAAQ,CAAC,yBAAyB,CAAC,EAAE,qDAAqD,CAAC;IAC3F,QAAQ,CAAC,UAAU,CAAC,EAAE,sCAAsC,CAAC;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,0CAA0C,CAAC;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,0CAA0C,CAAC;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,uCAAuC,CAAC;CAChE;AAED;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,qDAAqD,EAC7D,0BAA0B,EAAE,yCAAyC,EACrE,eAAe,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAmC,EACxG,gBAAgB,GAAE,6BAAkC,GACnD,4BAA4B,EAAE,CAiIhC"}

package/dist/esm/companion/application-documentation/technical-documentation-engine-content-bundle.js

@@ -1,3 +1,8 @@
+import { IMPLICIT_LEAD_SECTION_HEADING } from '../rendering/technical-documentation-markdown-links.js';
+import { APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_REF, } from './application-connection-documentation.js';
+import { APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_REF, } from './application-authentication-documentation.js';
+import { APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_REF, } from './application-integration-documentation.js';
+import { APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF, } from './application-administration-documentation.js';
 import { canonicalizeTechnicalDocumentationJson, TechnicalDocumentationAccessClass, TechnicalDocumentationApiReferenceSection, TechnicalDocumentationApiReferenceTargetKind, TechnicalDocumentationApplicabilityEvidenceAxis, TechnicalDocumentationApplicabilityEvidenceStatus, TechnicalDocumentationEditorialStatus, TechnicalDocumentationEvidenceSubjectRef, TechnicalDocumentationLinkKind, TechnicalDocumentationReaderAudience, TechnicalDocumentationSourceClassification, TechnicalDocumentationSourceOwnership, TechnicalDocumentationUnitKind, createTechnicalDocumentationUnitV1, } from '@wildo-ai/saas-specifications/technical-documentation';
 import { EngineDocumentationSpecificationFamilyRef, } from '@wildo-ai/saas-specifications/companion';
 import { APPLICATION_CONSUMER_DOCUMENTATION_CONSUMER_FACT_SOURCE_PREFIX, APPLICATION_CONSUMER_DOCUMENTATION_ENGINE_CONTENT_SOURCE_PREFIX, } from '../../content/application-consumer-documentation-content-manifest.schemas.js';
@@ -50,6 +55,20 @@ const A2A_INTEGRATION_APPLICABILITY_REQUIREMENTS = [{
 const CONSUMER_FACT_TOKEN_PATTERN = /\{\{CONSUMER_FACT:([^#}]+)#([^}]+)\}\}/g;
 const APPLICATION_ORGANIZATION_ROLES_TOKEN = '{{APPLICATION_ORGANIZATION_ROLES}}';
 const APPLICATION_ORGANIZATION_UNIT_RESOURCES_TOKEN = '{{APPLICATION_ORGANIZATION_UNIT_RESOURCES}}';
+/** Inline, and deliberately repeatable: a page names the product as often as its prose needs it. */
+const APPLICATION_NAME_TOKEN = '{{APPLICATION_NAME}}';
+/** Block, one per requested presentation — `{{APPLICATION_CONNECTION:baseUrls}}` and siblings. */
+// A selector may carry digits (`a2aAgentCard`), which an alphabetic-only class silently refuses:
+// the token then matches nothing and its page reads as declaring a projection it never used.
+const APPLICATION_CONNECTION_TOKEN_PATTERN = /\{\{APPLICATION_CONNECTION:([A-Za-z0-9]+)\}\}/g;
+/** Inline connection values, for use inside a sample where a block cannot go. */
+const APPLICATION_CONNECTION_VALUE_TOKEN_PATTERN = /\{\{APPLICATION_CONNECTION_VALUE:([A-Za-z0-9]+)\}\}/g;
+/** Same shape for the application's authentication policy. */
+const APPLICATION_AUTHENTICATION_TOKEN_PATTERN = /\{\{APPLICATION_AUTHENTICATION:([A-Za-z0-9]+)\}\}/g;
+/** Same shape again for who may perform each administrative action. */
+const APPLICATION_ADMINISTRATION_TOKEN_PATTERN = /\{\{APPLICATION_ADMINISTRATION:([A-Za-z0-9]+)\}\}/g;
+/** Same shape again for the tools and events this application publishes. */
+const APPLICATION_INTEGRATION_TOKEN_PATTERN = /\{\{APPLICATION_INTEGRATION:([A-Za-z0-9]+)\}\}/g;
 /**
  * Build one semantic guide-to-reference link without embedding a Docusaurus
  * route. The verified OpenAPI link index resolves the resource only when the
@@ -1357,6 +1376,7 @@ export const ENGINE_CONTENT_UNIT_DEFINITIONS = Object.freeze({
         accessClass: TechnicalDocumentationAccessClass.PUBLIC,
         applicabilityRequirements: [],
         relatedUnitRefs: [
+            'technical-documentation:unit/rest-api-conventions',
             'technical-documentation:unit/send-api-request',
             'technical-documentation:unit/work-with-api-collections',
             'technical-documentation:unit/write-and-reconcile-api-changes',
@@ -1370,6 +1390,29 @@ export const ENGINE_CONTENT_UNIT_DEFINITIONS = Object.freeze({
                 },
             }],
     },
+    'technical-documentation:unit/rest-api-conventions': {
+        kind: TechnicalDocumentationUnitKind.REFERENCE,
+        readerAudiences: [
+            TechnicalDocumentationReaderAudience.CONSUMING_INTERNAL_SERVICE,
+            TechnicalDocumentationReaderAudience.EXTERNAL_INTEGRATION_DEVELOPER,
+            TechnicalDocumentationReaderAudience.ORGANIZATION_INTEGRATION_DEVELOPER,
+        ],
+        accessClass: TechnicalDocumentationAccessClass.PUBLIC,
+        applicabilityRequirements: [],
+        relatedUnitRefs: [
+            'technical-documentation:unit/common-rest-api',
+            'technical-documentation:unit/send-api-request',
+            'technical-documentation:unit/write-and-reconcile-api-changes',
+            'technical-documentation:unit/troubleshoot-api-request',
+        ],
+        apiReferenceTargets: [{
+                label: 'API reference',
+                target: {
+                    section: TechnicalDocumentationApiReferenceSection.API_REFERENCE,
+                    kind: TechnicalDocumentationApiReferenceTargetKind.ROOT,
+                },
+            }],
+    },
     'technical-documentation:unit/send-api-request': {
         kind: TechnicalDocumentationUnitKind.QUICKSTART,
         readerAudiences: [
@@ -1564,7 +1607,7 @@ function parseEngineMarkdown(markdown, unitRef) {
         throw new Error(`engine content ${unitRef} must begin with exactly one H1 title`);
     const title = titleLine.slice(2).trim();
     const sections = [];
-    let heading = 'Overview';
+    let heading = IMPLICIT_LEAD_SECTION_HEADING;
     let body = [];
     const flush = () => {
         const bodyMarkdown = body.join('\n').trim();
@@ -1591,7 +1634,7 @@ function parseEngineMarkdown(markdown, unitRef) {
     // An explicit H2 is not rewritten: its author chose a real section and may
     // intentionally need the opening paragraph in its body.
     const [firstSection, ...remainingSections] = sections;
-    if (firstSection !== undefined && firstSection.heading === 'Overview') {
+    if (firstSection !== undefined && firstSection.heading === IMPLICIT_LEAD_SECTION_HEADING) {
         const overviewRemainder = firstSection.bodyMarkdown.replace(/^.*?(?:\n\s*\n|$)/s, '').trim();
         return {
             title,
@@ -1733,6 +1776,105 @@ function resolveConsumerFactMarkdown(markdown, declaredSourceRefs, catalog) {
         entriesBySourceRef: new Map([...resolvedFactRefs].map((sourceRef) => [sourceRef, catalogEntriesBySourceRef.get(sourceRef)])),
     };
 }
+/**
+ * Substitutes a companion projection that offers NAMED PRESENTATIONS, and optionally one inline
+ * value repeated as often as the prose needs it.
+ *
+ * Shared by the connection and authentication projections because both have the same shape and the
+ * same three failure modes: a page that uses a token without declaring the source, a page that
+ * declares the source and uses no token, and a page that asks for a presentation the projection
+ * does not offer. Each must fail the publication rather than render something plausible.
+ */
+function resolveSelectorProjectionMarkdown(input) {
+    const { markdown, declaredSourceRefs, sourceRef, label, fact, selectorPattern, presentationFor, inline, inlineSelector } = input;
+    const declaredRefs = declaredSourceRefs.filter((candidate) => candidate === sourceRef);
+    const inlineCount = inline === undefined ? 0 : markdown.split(inline.token).length - 1;
+    const selectorCount = [...markdown.matchAll(selectorPattern)].length;
+    const inlineSelectorCount = inlineSelector === undefined ? 0 : [...markdown.matchAll(inlineSelector.pattern)].length;
+    if (inlineCount === 0 && selectorCount === 0 && inlineSelectorCount === 0) {
+        if (declaredRefs.length > 0)
+            throw new Error(`engine content declares an unused ${label} projection: ${declaredRefs.join(', ')}`);
+        return { markdown, fact: undefined };
+    }
+    if (declaredRefs.length !== 1 || fact === undefined || declaredRefs[0] !== fact.sourceRef) {
+        throw new Error(`engine content ${label} projection must declare and resolve exactly one matching companion source`);
+    }
+    const withInline = inline === undefined ? markdown : markdown.split(inline.token).join(inline.valueFor(fact));
+    const withInlineSelectors = inlineSelector === undefined ? withInline : withInline.replace(inlineSelector.pattern, (_token, selector) => {
+        const value = inlineSelector.valueFor(fact, selector);
+        if (value === undefined || value.trim().length === 0) {
+            throw new Error(`engine content requests an unknown or empty ${label} inline value: ${selector}`);
+        }
+        return value;
+    });
+    const rendered = withInlineSelectors.replace(selectorPattern, (_token, selector) => {
+        const presentation = presentationFor(fact, selector);
+        if (presentation === undefined) {
+            throw new Error(`engine content requests an unknown ${label} presentation: ${selector}`);
+        }
+        if (presentation.trim().length === 0) {
+            throw new Error(`${label} presentation ${selector} rendered empty; every presentation must say something true even when the subject is absent`);
+        }
+        return presentation;
+    });
+    return { markdown: rendered, fact };
+}
+/**
+ * The application's own name and connection details. The name is inline and repeatable — a page
+ * names the product as often as its prose needs it — while a connection table is a block.
+ */
+function resolveApplicationConnectionMarkdown(markdown, declaredSourceRefs, fact) {
+    return resolveSelectorProjectionMarkdown({
+        markdown,
+        declaredSourceRefs,
+        sourceRef: APPLICATION_CONNECTION_DOCUMENTATION_SOURCE_REF,
+        label: 'application-connection',
+        fact,
+        selectorPattern: APPLICATION_CONNECTION_TOKEN_PATTERN,
+        presentationFor: (resolved, selector) => resolved.presentations[selector],
+        inline: { token: APPLICATION_NAME_TOKEN, valueFor: (resolved) => resolved.applicationName },
+        inlineSelector: {
+            pattern: APPLICATION_CONNECTION_VALUE_TOKEN_PATTERN,
+            valueFor: (resolved, selector) => resolved.inlineValues[selector],
+        },
+    });
+}
+/** What this application actually asks of a person signing in. Presentations only. */
+function resolveApplicationAuthenticationMarkdown(markdown, declaredSourceRefs, fact) {
+    return resolveSelectorProjectionMarkdown({
+        markdown,
+        declaredSourceRefs,
+        sourceRef: APPLICATION_AUTHENTICATION_DOCUMENTATION_SOURCE_REF,
+        label: 'application-authentication',
+        fact,
+        selectorPattern: APPLICATION_AUTHENTICATION_TOKEN_PATTERN,
+        presentationFor: (resolved, selector) => resolved.presentations[selector],
+    });
+}
+/** The tools and events this application publishes. Presentations only. */
+function resolveApplicationIntegrationMarkdown(markdown, declaredSourceRefs, fact) {
+    return resolveSelectorProjectionMarkdown({
+        markdown,
+        declaredSourceRefs,
+        sourceRef: APPLICATION_INTEGRATION_DOCUMENTATION_SOURCE_REF,
+        label: 'application-integration',
+        fact,
+        selectorPattern: APPLICATION_INTEGRATION_TOKEN_PATTERN,
+        presentationFor: (resolved, selector) => resolved.presentations[selector],
+    });
+}
+/** Who may perform each administrative action here. Presentations only. */
+function resolveApplicationAdministrationMarkdown(markdown, declaredSourceRefs, fact) {
+    return resolveSelectorProjectionMarkdown({
+        markdown,
+        declaredSourceRefs,
+        sourceRef: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF,
+        label: 'application-administration',
+        fact,
+        selectorPattern: APPLICATION_ADMINISTRATION_TOKEN_PATTERN,
+        presentationFor: (resolved, selector) => resolved.presentations[selector],
+    });
+}
 function resolveApplicationOrganizationRolesMarkdown(markdown, declaredSourceRefs, fact) {
     const declaredRefs = declaredSourceRefs.filter((sourceRef) => sourceRef === APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_REF);
     const tokenCount = markdown.split(APPLICATION_ORGANIZATION_ROLES_TOKEN).length - 1;
@@ -1764,10 +1906,10 @@ function resolveApplicationOrganizationUnitResourcesMarkdown(markdown, declaredS
     return { markdown: markdown.replace(APPLICATION_ORGANIZATION_UNIT_RESOURCES_TOKEN, fact.markdown), fact };
 }
 /**
- * Compiles verified engine content and the two explicit application facts
- * (organization roles and unit-aware resources) into private documentation.
+ * Compiles verified engine content and the application's own facts (organization roles,
+ * unit-aware resources, name and connection details) into private documentation.
  */
-export function projectEngineApplicationConsumerContentBundle(bundle, engineSpecificationCatalog, unitDefinitions = ENGINE_CONTENT_UNIT_DEFINITIONS, applicationOrganizationRolesFact, applicationOrganizationUnitResourcesFact) {
+export function projectEngineApplicationConsumerContentBundle(bundle, engineSpecificationCatalog, unitDefinitions = ENGINE_CONTENT_UNIT_DEFINITIONS, applicationFacts = {}) {
     const manifestRefs = bundle.manifest.units.map((unit) => unit.unitRef).sort();
     const definitionRefs = Object.keys(unitDefinitions).sort();
     if (manifestRefs.join('\0') !== definitionRefs.join('\0')) {
@@ -1778,13 +1920,21 @@ export function projectEngineApplicationConsumerContentBundle(bundle, engineSpec
             throw new Error(`engine content unit ${identity.unitRef} must resolve to exactly one Markdown source`);
         const authoredMarkdown = new TextDecoder('utf-8', { fatal: true }).decode(bundle.readManagedBytes(identity.managedPaths[0]));
         const resolvedConsumerFacts = resolveConsumerFactMarkdown(authoredMarkdown, identity.sourceRefs, engineSpecificationCatalog);
-        const resolvedApplicationOrganizationRoles = resolveApplicationOrganizationRolesMarkdown(resolvedConsumerFacts.markdown, identity.sourceRefs, applicationOrganizationRolesFact);
-        const resolvedApplicationOrganizationUnitResources = resolveApplicationOrganizationUnitResourcesMarkdown(resolvedApplicationOrganizationRoles.markdown, identity.sourceRefs, applicationOrganizationUnitResourcesFact);
+        const resolvedApplicationOrganizationRoles = resolveApplicationOrganizationRolesMarkdown(resolvedConsumerFacts.markdown, identity.sourceRefs, applicationFacts.organizationRoles);
+        const resolvedApplicationOrganizationUnitResources = resolveApplicationOrganizationUnitResourcesMarkdown(resolvedApplicationOrganizationRoles.markdown, identity.sourceRefs, applicationFacts.organizationUnitResources);
+        const resolvedApplicationConnection = resolveApplicationConnectionMarkdown(resolvedApplicationOrganizationUnitResources.markdown, identity.sourceRefs, applicationFacts.connection);
+        const resolvedApplicationAuthentication = resolveApplicationAuthenticationMarkdown(resolvedApplicationConnection.markdown, identity.sourceRefs, applicationFacts.authentication);
+        const resolvedApplicationAdministration = resolveApplicationAdministrationMarkdown(resolvedApplicationAuthentication.markdown, identity.sourceRefs, applicationFacts.administration);
+        const resolvedApplicationIntegration = resolveApplicationIntegrationMarkdown(resolvedApplicationAdministration.markdown, identity.sourceRefs, applicationFacts.integration);
         return [identity.unitRef, {
-                parsed: parseEngineMarkdown(resolvedApplicationOrganizationUnitResources.markdown, identity.unitRef),
+                parsed: parseEngineMarkdown(resolvedApplicationIntegration.markdown, identity.unitRef),
                 resolvedConsumerFacts,
                 resolvedApplicationOrganizationRoles,
                 resolvedApplicationOrganizationUnitResources,
+                resolvedApplicationConnection,
+                resolvedApplicationAuthentication,
+                resolvedApplicationAdministration,
+                resolvedApplicationIntegration,
             }];
     }));
     const relatedTargetByUnitRef = new Map(bundle.manifest.units.map((identity) => {
@@ -1813,7 +1963,7 @@ export function projectEngineApplicationConsumerContentBundle(bundle, engineSpec
         const content = parsedContentByUnitRef.get(identity.unitRef);
         if (content === undefined)
             throw new Error(`engine content ${identity.unitRef} has no parsed content`);
-        const { parsed, resolvedConsumerFacts, resolvedApplicationOrganizationRoles, resolvedApplicationOrganizationUnitResources } = content;
+        const { parsed, resolvedConsumerFacts, resolvedApplicationOrganizationRoles, resolvedApplicationOrganizationUnitResources, resolvedApplicationConnection, resolvedApplicationAuthentication, resolvedApplicationAdministration, resolvedApplicationIntegration } = content;
         const unitSlug = identity.unitRef.slice(identity.unitRef.lastIndexOf('/') + 1);
         const relatedTargets = resolveRelatedUnitLinkTargets(identity.unitRef, definition.relatedUnitRefs, relatedTargetByUnitRef);
         const ownProvenance = identity.sourceRefs.map((sourceRef) => {
@@ -1822,7 +1972,13 @@ export function projectEngineApplicationConsumerContentBundle(bundle, engineSpec
                 ? resolvedApplicationOrganizationRoles.fact
                 : resolvedApplicationOrganizationUnitResources.fact?.sourceRef === sourceRef
                     ? resolvedApplicationOrganizationUnitResources.fact
-                    : undefined;
+                    : resolvedApplicationConnection.fact?.sourceRef === sourceRef
+                        ? resolvedApplicationConnection.fact
+                        : resolvedApplicationAuthentication.fact?.sourceRef === sourceRef
+                            ? resolvedApplicationAuthentication.fact
+                            : resolvedApplicationAdministration.fact?.sourceRef === sourceRef
+                                ? resolvedApplicationAdministration.fact
+                                : undefined;
             return {
                 sourceRef,
                 ownership: applicationProjection === undefined