@wildo-ai/saas-technical-doc 1.1.4 → 1.1.6

package/dist/esm/build/csp-emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csp-emit.d.ts","sourceRoot":"","sources":["../../../src/build/csp-emit.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,IAAI,wBAAwB,EAG5C,gBAAgB,IAAI,wBAAwB,EAC5C,0BAA0B,IAAI,kCAAkC,EAChE,gCAAgC,IAAI,wCAAwC,EAC5E,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,CAAC;AAEF,eAAO,MAAM,sBAAsB,0BAAkC,CAAC;AACtE,eAAO,MAAM,oBAAoB,wBAAgC,CAAC;AAClE,eAAO,MAAM,gBAAgB,iCAA2B,CAAC;AACzD,eAAO,MAAM,gBAAgB,iCAA2B,CAAC;AACzD,eAAO,MAAM,0BAA0B,2CAAqC,CAAC;AAC7E,eAAO,MAAM,gCAAgC,iDAA2C,CAAC"}
+{"version":3,"file":"csp-emit.d.ts","sourceRoot":"","sources":["../../../../src/build/csp-emit.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,IAAI,wBAAwB,EAG5C,gBAAgB,IAAI,wBAAwB,EAC5C,0BAA0B,IAAI,kCAAkC,EAChE,gCAAgC,IAAI,wCAAwC,EAC5E,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,CAAC;AAEF,eAAO,MAAM,sBAAsB,0BAAkC,CAAC;AACtE,eAAO,MAAM,oBAAoB,wBAAgC,CAAC;AAClE,eAAO,MAAM,gBAAgB,iCAA2B,CAAC;AACzD,eAAO,MAAM,gBAAgB,iCAA2B,CAAC;AACzD,eAAO,MAAM,0BAA0B,2CAAqC,CAAC;AAC7E,eAAO,MAAM,gCAAgC,iDAA2C,CAAC"}

package/dist/esm/build/load-materialized-frontend-providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-materialized-frontend-providers.d.ts","sourceRoot":"","sources":["../../../src/build/load-materialized-frontend-providers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iCAAiC,EACjC,mCAAmC,GACpC,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"load-materialized-frontend-providers.d.ts","sourceRoot":"","sources":["../../../../src/build/load-materialized-frontend-providers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iCAAiC,EACjC,mCAAmC,GACpC,MAAM,+BAA+B,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"application-administration-documentation.d.ts","sourceRoot":"","sources":["../../../../src/companion/application-documentation/application-administration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mDAAmD,EAAG,wDAAiE,CAAC;AACrI,eAAO,MAAM,uDAAuD,IAAI,CAAC;AAEzE,MAAM,WAAW,qCAAqC;IACpD,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,aAAa,EAAE,SAAS,qCAAqC,EAAE,CAAC;IACzE,QAAQ,CAAC,uBAAuB,EAAE,SAAS,qCAAqC,EAAE,CAAC;CACpF;AAED,+FAA+F;AAC/F,oBAAY,qCAAqC;IAC/C,wGAAwG;IACxG,cAAc,kBAAkB;IAChC,oEAAoE;IACpE,yBAAyB,4BAA4B;CACtD;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,qCAAqC,EAAE,MAAM,CAAC,CAAC,CAAC;CACzF;AAoBD;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,4CAA4C,GACnD,0CAA0C,CAoB5C"}
+{"version":3,"file":"application-administration-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-administration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mDAAmD,EAAG,wDAAiE,CAAC;AACrI,eAAO,MAAM,uDAAuD,IAAI,CAAC;AAEzE,MAAM,WAAW,qCAAqC;IACpD,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,aAAa,EAAE,SAAS,qCAAqC,EAAE,CAAC;IACzE,QAAQ,CAAC,uBAAuB,EAAE,SAAS,qCAAqC,EAAE,CAAC;CACpF;AAED,+FAA+F;AAC/F,oBAAY,qCAAqC;IAC/C,wGAAwG;IACxG,cAAc,kBAAkB;IAChC,oEAAoE;IACpE,yBAAyB,4BAA4B;CACtD;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,qCAAqC,EAAE,MAAM,CAAC,CAAC,CAAC;CACzF;AAoBD;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,4CAA4C,GACnD,0CAA0C,CAoB5C"}

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

@@ -1 +1 @@
-{"version":3,"file":"application-administration-documentation.js","sourceRoot":"","sources":["../../../../src/companion/application-documentation/application-administration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mDAAmD,GAAG,wDAAiE,CAAC;AACrI,MAAM,CAAC,MAAM,uDAAuD,GAAG,CAAC,CAAC;AAuBzE,+FAA+F;AAC/F,MAAM,CAAN,IAAY,qCAKX;AALD,WAAY,qCAAqC;IAC/C,wGAAwG;IACxG,yEAAgC,CAAA;IAChC,oEAAoE;IACpE,8FAAqD,CAAA;AACvD,CAAC,EALW,qCAAqC,KAArC,qCAAqC,QAKhD;AAQD,SAAS,YAAY,CACnB,OAAyD,EACzD,YAAoB;IAEpB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IAC9C,MAAM,IAAI,GAAG,OAAO;SACjB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACd,MAAM,GAAG,GAAG,MAAM,CAAC,iBAAiB;YAClC,CAAC,CAAC,uCAAuC;YACzC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;gBAC9B,CAAC,CAAC,sCAAsC;gBACxC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,KAAK,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC;IACzC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,mDAAmD,IAAI,wPAAwP,CAAC;AACzT,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6CAA6C,CAC3D,MAAoD;IAEpD,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,GAAG,MAAM,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAClF,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IACD,OAAO;QACL,SAAS,EAAE,mDAAmD;QAC9D,aAAa,EAAE,uDAAuD;QACtE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC;YAC3B,CAAC,qCAAqC,CAAC,cAAc,CAAC,EAAE,YAAY,CAClE,MAAM,CAAC,aAAa,EACpB,6HAA6H,CAC9H;YACD,CAAC,qCAAqC,CAAC,yBAAyB,CAAC,EAAE,YAAY,CAC7E,MAAM,CAAC,uBAAuB,EAC9B,oGAAoG,CACrG;SACF,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Who may perform each administrative action in THIS application.\n *\n * The roles page lists the roles and what each is for; it could not say which role may actually\n * invite a person, change their access or move a team, because that lives on the operations —\n * every one of which declares the roles it accepts. An administrator's first question (\"can a\n * manager do this, or does it need an owner?\") therefore had no answer anywhere in the portal, and\n * the pages fell back on prose about least privilege.\n *\n * The projection joins two things the companion already holds: the admitted operations for the\n * membership and organization-unit resources, and the application's own role labels. It is a\n * matrix of what this application publishes, not a restatement of the framework's defaults.\n */\nexport const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-administration' as const;\nexport const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION = 1;\n\nexport interface ApplicationAdministrationActionSource {\n  /** What the action does, in the words the API reference uses for the same operation. */\n  readonly action: string;\n  /**\n   * Labels of the organization roles that may perform it, in the application's own words.\n   * Empty means the operation declares no role gate — see `openToEveryMember`.\n   */\n  readonly roleLabels: readonly string[];\n  /**\n   * True when the operation declares no required role. That is a real, intentional state (any\n   * authenticated member of the organization may call it), not a gap in the projection, so it is\n   * said explicitly rather than shown as an empty cell.\n   */\n  readonly openToEveryMember: boolean;\n}\n\nexport interface ApplicationAdministrationDocumentationSource {\n  readonly memberActions: readonly ApplicationAdministrationActionSource[];\n  readonly organizationUnitActions: readonly ApplicationAdministrationActionSource[];\n}\n\n/** Named presentations a page may request with `{{APPLICATION_ADMINISTRATION:<selector>}}`. */\nexport enum ApplicationAdministrationPresentation {\n  /** Membership actions — invite, change access, suspend, remove — against the roles that may do them. */\n  MEMBER_ACTIONS = 'memberActions',\n  /** Organization-unit actions against the roles that may do them. */\n  ORGANIZATION_UNIT_ACTIONS = 'organizationUnitActions',\n}\n\nexport interface ApplicationAdministrationDocumentationFact {\n  readonly sourceRef: string;\n  readonly sourceVersion: number;\n  readonly presentations: Readonly<Record<ApplicationAdministrationPresentation, string>>;\n}\n\nfunction actionsTable(\n  actions: readonly ApplicationAdministrationActionSource[],\n  emptyMessage: string,\n): string {\n  if (actions.length === 0) return emptyMessage;\n  const rows = actions\n    .map((action) => {\n      const who = action.openToEveryMember\n        ? 'Any active member of the organization'\n        : action.roleLabels.length === 0\n          ? 'Not published for organization roles'\n          : action.roleLabels.join(', ');\n      return `| ${action.action} | ${who} |`;\n    })\n    .join('\\n');\n  return `| Action | Who may perform it |\\n| --- | --- |\\n${rows}\\n\\nA role higher in the inheritance chain can do everything the roles below it can, so a role that is not named here may still qualify through the role it includes. The operation contract in the API reference is authoritative for one exact call.`;\n}\n\n/**\n * Projects the administrative matrix. A pure function of the source, so two runs over the same\n * application produce identical bytes.\n */\nexport function projectApplicationAdministrationDocumentation(\n  source: ApplicationAdministrationDocumentationSource,\n): ApplicationAdministrationDocumentationFact {\n  for (const action of [...source.memberActions, ...source.organizationUnitActions]) {\n    if (action.action.trim().length === 0) {\n      throw new Error('application administration projection received an action with no description');\n    }\n  }\n  return {\n    sourceRef: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF,\n    sourceVersion: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION,\n    presentations: Object.freeze({\n      [ApplicationAdministrationPresentation.MEMBER_ACTIONS]: actionsTable(\n        source.memberActions,\n        'This application publishes no membership administration operations, so member access is managed outside this documentation.',\n      ),\n      [ApplicationAdministrationPresentation.ORGANIZATION_UNIT_ACTIONS]: actionsTable(\n        source.organizationUnitActions,\n        'This application does not publish organization units, so there are no unit administration actions.',\n      ),\n    }),\n  };\n}\n"]}
+{"version":3,"file":"application-administration-documentation.js","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-administration-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mDAAmD,GAAG,wDAAiE,CAAC;AACrI,MAAM,CAAC,MAAM,uDAAuD,GAAG,CAAC,CAAC;AAuBzE,+FAA+F;AAC/F,MAAM,CAAN,IAAY,qCAKX;AALD,WAAY,qCAAqC;IAC/C,wGAAwG;IACxG,yEAAgC,CAAA;IAChC,oEAAoE;IACpE,8FAAqD,CAAA;AACvD,CAAC,EALW,qCAAqC,KAArC,qCAAqC,QAKhD;AAQD,SAAS,YAAY,CACnB,OAAyD,EACzD,YAAoB;IAEpB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IAC9C,MAAM,IAAI,GAAG,OAAO;SACjB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACd,MAAM,GAAG,GAAG,MAAM,CAAC,iBAAiB;YAClC,CAAC,CAAC,uCAAuC;YACzC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;gBAC9B,CAAC,CAAC,sCAAsC;gBACxC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,KAAK,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC;IACzC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,mDAAmD,IAAI,wPAAwP,CAAC;AACzT,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6CAA6C,CAC3D,MAAoD;IAEpD,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,GAAG,MAAM,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAClF,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IACD,OAAO;QACL,SAAS,EAAE,mDAAmD;QAC9D,aAAa,EAAE,uDAAuD;QACtE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC;YAC3B,CAAC,qCAAqC,CAAC,cAAc,CAAC,EAAE,YAAY,CAClE,MAAM,CAAC,aAAa,EACpB,6HAA6H,CAC9H;YACD,CAAC,qCAAqC,CAAC,yBAAyB,CAAC,EAAE,YAAY,CAC7E,MAAM,CAAC,uBAAuB,EAC9B,oGAAoG,CACrG;SACF,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Who may perform each administrative action in THIS application.\n *\n * The roles page lists the roles and what each is for; it could not say which role may actually\n * invite a person, change their access or move a team, because that lives on the operations —\n * every one of which declares the roles it accepts. An administrator's first question (\"can a\n * manager do this, or does it need an owner?\") therefore had no answer anywhere in the portal, and\n * the pages fell back on prose about least privilege.\n *\n * The projection joins two things the companion already holds: the admitted operations for the\n * membership and organization-unit resources, and the application's own role labels. It is a\n * matrix of what this application publishes, not a restatement of the framework's defaults.\n */\nexport const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:application-administration' as const;\nexport const APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION = 1;\n\nexport interface ApplicationAdministrationActionSource {\n  /** What the action does, in the words the API reference uses for the same operation. */\n  readonly action: string;\n  /**\n   * Labels of the organization roles that may perform it, in the application's own words.\n   * Empty means the operation declares no role gate — see `openToEveryMember`.\n   */\n  readonly roleLabels: readonly string[];\n  /**\n   * True when the operation declares no required role. That is a real, intentional state (any\n   * authenticated member of the organization may call it), not a gap in the projection, so it is\n   * said explicitly rather than shown as an empty cell.\n   */\n  readonly openToEveryMember: boolean;\n}\n\nexport interface ApplicationAdministrationDocumentationSource {\n  readonly memberActions: readonly ApplicationAdministrationActionSource[];\n  readonly organizationUnitActions: readonly ApplicationAdministrationActionSource[];\n}\n\n/** Named presentations a page may request with `{{APPLICATION_ADMINISTRATION:<selector>}}`. */\nexport enum ApplicationAdministrationPresentation {\n  /** Membership actions — invite, change access, suspend, remove — against the roles that may do them. */\n  MEMBER_ACTIONS = 'memberActions',\n  /** Organization-unit actions against the roles that may do them. */\n  ORGANIZATION_UNIT_ACTIONS = 'organizationUnitActions',\n}\n\nexport interface ApplicationAdministrationDocumentationFact {\n  readonly sourceRef: string;\n  readonly sourceVersion: number;\n  readonly presentations: Readonly<Record<ApplicationAdministrationPresentation, string>>;\n}\n\nfunction actionsTable(\n  actions: readonly ApplicationAdministrationActionSource[],\n  emptyMessage: string,\n): string {\n  if (actions.length === 0) return emptyMessage;\n  const rows = actions\n    .map((action) => {\n      const who = action.openToEveryMember\n        ? 'Any active member of the organization'\n        : action.roleLabels.length === 0\n          ? 'Not published for organization roles'\n          : action.roleLabels.join(', ');\n      return `| ${action.action} | ${who} |`;\n    })\n    .join('\\n');\n  return `| Action | Who may perform it |\\n| --- | --- |\\n${rows}\\n\\nA role higher in the inheritance chain can do everything the roles below it can, so a role that is not named here may still qualify through the role it includes. The operation contract in the API reference is authoritative for one exact call.`;\n}\n\n/**\n * Projects the administrative matrix. A pure function of the source, so two runs over the same\n * application produce identical bytes.\n */\nexport function projectApplicationAdministrationDocumentation(\n  source: ApplicationAdministrationDocumentationSource,\n): ApplicationAdministrationDocumentationFact {\n  for (const action of [...source.memberActions, ...source.organizationUnitActions]) {\n    if (action.action.trim().length === 0) {\n      throw new Error('application administration projection received an action with no description');\n    }\n  }\n  return {\n    sourceRef: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_REF,\n    sourceVersion: APPLICATION_ADMINISTRATION_DOCUMENTATION_SOURCE_VERSION,\n    presentations: Object.freeze({\n      [ApplicationAdministrationPresentation.MEMBER_ACTIONS]: actionsTable(\n        source.memberActions,\n        'This application publishes no membership administration operations, so member access is managed outside this documentation.',\n      ),\n      [ApplicationAdministrationPresentation.ORGANIZATION_UNIT_ACTIONS]: actionsTable(\n        source.organizationUnitActions,\n        'This application does not publish organization units, so there are no unit administration actions.',\n      ),\n    }),\n  };\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"application-authentication-documentation.d.ts","sourceRoot":"","sources":["../../../../src/companion/application-documentation/application-authentication-documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA8D,MAAM,uBAAuB,CAAC;AAG/G;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mDAAmD,EAAG,wDAAiE,CAAC;AACrI,eAAO,MAAM,uDAAuD,IAAI,CAAC;AAEzE,MAAM,WAAW,uCAAuC;IACtD,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,cAAc,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;QACjC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;QAC3C,QAAQ,CAAC,4BAA4B,EAAE,OAAO,CAAC;QAC/C,kEAAkE;QAClE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;KACpD,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;QACjC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;QACtC,4EAA4E;QAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;QACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;QAC9B,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;KAC7C,CAAC;CACH;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,SAAS,EAAE,SAAS,uCAAuC,EAAE,CAAC;CACxE;AAED,+FAA+F;AAC/F,oBAAY,qCAAqC;IAC/C,mEAAmE;IACnE,uBAAuB,yBAAyB;IAChD,2FAA2F;IAC3F,kBAAkB,sBAAsB;IACxC,gDAAgD;IAChD,cAAc,kBAAkB;IAChC,wEAAwE;IACxE,mBAAmB,sBAAsB;CAC1C;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,qCAAqC,EAAE,MAAM,CAAC,CAAC,CAAC;CACzF;AAoED;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,4CAA4C,GACnD,0CAA0C,CAmB5C"}
+{"version":3,"file":"application-authentication-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-authentication-documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA8D,MAAM,uBAAuB,CAAC;AAG/G;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mDAAmD,EAAG,wDAAiE,CAAC;AACrI,eAAO,MAAM,uDAAuD,IAAI,CAAC;AAEzE,MAAM,WAAW,uCAAuC;IACtD,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,cAAc,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;QACjC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;QAC3C,QAAQ,CAAC,4BAA4B,EAAE,OAAO,CAAC;QAC/C,kEAAkE;QAClE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;KACpD,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;QACjC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;QACtC,4EAA4E;QAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KACzC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;QACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;QAC9B,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;KAC7C,CAAC;CACH;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,SAAS,EAAE,SAAS,uCAAuC,EAAE,CAAC;CACxE;AAED,+FAA+F;AAC/F,oBAAY,qCAAqC;IAC/C,mEAAmE;IACnE,uBAAuB,yBAAyB;IAChD,2FAA2F;IAC3F,kBAAkB,sBAAsB;IACxC,gDAAgD;IAChD,cAAc,kBAAkB;IAChC,wEAAwE;IACxE,mBAAmB,sBAAsB;CAC1C;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,qCAAqC,EAAE,MAAM,CAAC,CAAC,CAAC;CACzF;AAoED;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,4CAA4C,GACnD,0CAA0C,CAmB5C"}

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

@@ -102,6 +102,43 @@ export interface ApplicationConnectionDocumentationFact {
     readonly presentations: Readonly<Record<ApplicationConnectionPresentation, string>>;
     readonly inlineValues: Readonly<Record<ApplicationConnectionInlineValue, string>>;
 }
+/**
+ * How the PRIMARY origin is rendered: as a build-time token, never as the origin generation happened
+ * to see (#1203).
+ *
+ * ## The defect
+ *
+ * A documentation image built for staging shipped 42 occurrences of `http://localhost:4241` — the
+ * SCIM base URL an administrator pastes into their identity provider, the MCP and A2A endpoints, and
+ * the `servers` of the published API description. Generation resolved this value on a developer
+ * machine, and the resolved bytes are committed, so every later build carried that environment's
+ * origin whatever it was built for. The CSP got a per-environment regeneration step; the CONTENT got
+ * none.
+ *
+ * ## Why a token rather than regenerating per environment
+ *
+ * Regenerating the content in the deploy workflow needs a CLI entry point for a companion-owned
+ * generation — heavy for a deploy job — and would still leave the committed artifacts describing
+ * whoever generated them last. A token makes the generated content environment-INDEPENDENT, which is
+ * the honest thing for a committed artifact, and moves the environment decision to the only place
+ * that knows it: the image build, which already receives `WILDO_DOCS_API_BASE_URL` as a docker build
+ * argument (`ci-workflow-generator.service.ts` declares it for `AppFrontendType.TECH_DOC`).
+ *
+ * It also covers the static OpenAPI documents, which are served as files and have no runtime to read
+ * `customFields` from — the reason the runtime-substitution option cannot be the whole answer.
+ *
+ * ## Only the PRIMARY origin
+ *
+ * Additional entries in `apiServers` are explicitly authored per-environment declarations; a reader
+ * who lists several is naming them deliberately and each is already correct. The primary is the one
+ * every sample interpolates, and the one an image is built FOR.
+ */
+export declare const DOCS_API_ORIGIN_TOKEN = "__WILDO_DOCS_API_ORIGIN__";
+/**
+ * Shown when the application publishes no base URL at all. Unchanged by #1203: there is no origin to
+ * defer, so the reader is told to substitute their own — which is what this always said.
+ */
+export declare const UNPUBLISHED_BASE_URL_STAND_IN = "https://your-environment.example";
 /**
  * Projects the application's connection facts into the presentations a page may
  * request. Every presentation is a pure function of the source, so two runs over

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

@@ -1 +1 @@
-{"version":3,"file":"application-connection-documentation.d.ts","sourceRoot":"","sources":["../../../../src/companion/application-documentation/application-connection-documentation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,+CAA+C,EAAG,oDAA6D,CAAC;AAC7H,eAAO,MAAM,mDAAmD,IAAI,CAAC;AAErE,kFAAkF;AAClF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wCAAwC;IACvD,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,2FAA2F;AAC3F,oBAAY,iCAAiC;IAC3C,uFAAuF;IACvF,kBAAkB,sBAAsB;IACxC,gFAAgF;IAChF,SAAS,aAAa;IACtB;;;;;OAKG;IACH,YAAY,gBAAgB;IAC5B,yFAAyF;IACzF,cAAc,iBAAiB;CAChC;AAED;;;GAGG;AACH,oBAAY,gCAAgC;IAC1C,oGAAoG;IACpG,QAAQ,YAAY;IACpB,qDAAqD;IACrD,gBAAgB,mBAAmB;IACnC,mDAAmD;IACnD,cAAc,iBAAiB;IAC/B,sCAAsC;IACtC,cAAc,iBAAiB;IAC/B;;;;;;;;OAQG;IACH,aAAa,gBAAgB;IAC7B,kGAAkG;IAClG,YAAY,gBAAgB;IAC5B;;;;;;;;;;OAUG;IACH,kBAAkB,qBAAqB;CACxC;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,iCAAiC,EAAE,MAAM,CAAC,CAAC,CAAC;IACpF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,gCAAgC,EAAE,MAAM,CAAC,CAAC,CAAC;CACnF;AA0DD;;;;GAIG;AACH,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,wCAAwC,GAC/C,sCAAsC,CA2BxC"}
+{"version":3,"file":"application-connection-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-connection-documentation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,+CAA+C,EAAG,oDAA6D,CAAC;AAC7H,eAAO,MAAM,mDAAmD,IAAI,CAAC;AAErE,kFAAkF;AAClF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wCAAwC;IACvD,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,2FAA2F;AAC3F,oBAAY,iCAAiC;IAC3C,uFAAuF;IACvF,kBAAkB,sBAAsB;IACxC,gFAAgF;IAChF,SAAS,aAAa;IACtB;;;;;OAKG;IACH,YAAY,gBAAgB;IAC5B,yFAAyF;IACzF,cAAc,iBAAiB;CAChC;AAED;;;GAGG;AACH,oBAAY,gCAAgC;IAC1C,oGAAoG;IACpG,QAAQ,YAAY;IACpB,qDAAqD;IACrD,gBAAgB,mBAAmB;IACnC,mDAAmD;IACnD,cAAc,iBAAiB;IAC/B,sCAAsC;IACtC,cAAc,iBAAiB;IAC/B;;;;;;;;OAQG;IACH,aAAa,gBAAgB;IAC7B,kGAAkG;IAClG,YAAY,gBAAgB;IAC5B;;;;;;;;;;OAUG;IACH,kBAAkB,qBAAqB;CACxC;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,iCAAiC,EAAE,MAAM,CAAC,CAAC,CAAC;IACpF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,gCAAgC,EAAE,MAAM,CAAC,CAAC,CAAC;CACnF;AA0DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,6BAA6B,qCAAqC,CAAC;AAOhF;;;;GAIG;AACH,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,wCAAwC,GAC/C,sCAAsC,CA2BxC"}

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

@@ -86,7 +86,7 @@ function baseUrlsMarkdown(source) {
         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.`;
     }
     const rows = source.apiServers
-        .map((server) => `| \`${server.url}\` | ${server.description ?? 'Published base URL'} |`)
+        .map((server, index) => `| \`${renderServerUrl(source, index, server.url)}\` | ${server.description ?? 'Published base URL'} |`)
         .join('\n');
     return `| Base URL | Environment |\n| --- | --- |\n${rows}`;
 }
@@ -102,9 +102,9 @@ function a2aAgentCardMarkdown(source) {
 }
 function connectionDetailsMarkdown(source) {
     const rows = [];
-    for (const server of source.apiServers) {
-        rows.push(`| Base URL${server.description === undefined ? '' : ` (${server.description})`} | \`${server.url}\` |`);
-    }
+    source.apiServers.forEach((server, index) => {
+        rows.push(`| Base URL${server.description === undefined ? '' : ` (${server.description})`} | \`${renderServerUrl(source, index, server.url)}\` |`);
+    });
     rows.push(`| API mount | \`${MAIN_API_BASE_PATH}\` — every path in the API reference already includes it |`);
     if (source.surfaces.mcpToolServer) {
         rows.push(`| MCP endpoint | \`${publicRoutePath(ManualControllerRouteKey.MCP_ENDPOINT)}\` |`);
@@ -125,7 +125,48 @@ function connectionDetailsMarkdown(source) {
  */
 function primaryBaseUrl(source) {
     const first = source.apiServers[0];
-    return first === undefined ? 'https://your-environment.example' : first.url.replace(/\/+$/, '');
+    return first === undefined ? UNPUBLISHED_BASE_URL_STAND_IN : DOCS_API_ORIGIN_TOKEN;
+}
+/**
+ * How the PRIMARY origin is rendered: as a build-time token, never as the origin generation happened
+ * to see (#1203).
+ *
+ * ## The defect
+ *
+ * A documentation image built for staging shipped 42 occurrences of `http://localhost:4241` — the
+ * SCIM base URL an administrator pastes into their identity provider, the MCP and A2A endpoints, and
+ * the `servers` of the published API description. Generation resolved this value on a developer
+ * machine, and the resolved bytes are committed, so every later build carried that environment's
+ * origin whatever it was built for. The CSP got a per-environment regeneration step; the CONTENT got
+ * none.
+ *
+ * ## Why a token rather than regenerating per environment
+ *
+ * Regenerating the content in the deploy workflow needs a CLI entry point for a companion-owned
+ * generation — heavy for a deploy job — and would still leave the committed artifacts describing
+ * whoever generated them last. A token makes the generated content environment-INDEPENDENT, which is
+ * the honest thing for a committed artifact, and moves the environment decision to the only place
+ * that knows it: the image build, which already receives `WILDO_DOCS_API_BASE_URL` as a docker build
+ * argument (`ci-workflow-generator.service.ts` declares it for `AppFrontendType.TECH_DOC`).
+ *
+ * It also covers the static OpenAPI documents, which are served as files and have no runtime to read
+ * `customFields` from — the reason the runtime-substitution option cannot be the whole answer.
+ *
+ * ## Only the PRIMARY origin
+ *
+ * Additional entries in `apiServers` are explicitly authored per-environment declarations; a reader
+ * who lists several is naming them deliberately and each is already correct. The primary is the one
+ * every sample interpolates, and the one an image is built FOR.
+ */
+export const DOCS_API_ORIGIN_TOKEN = '__WILDO_DOCS_API_ORIGIN__';
+/**
+ * Shown when the application publishes no base URL at all. Unchanged by #1203: there is no origin to
+ * defer, so the reader is told to substitute their own — which is what this always said.
+ */
+export const UNPUBLISHED_BASE_URL_STAND_IN = 'https://your-environment.example';
+/** The primary server renders as the token; any further declared server renders as authored. */
+function renderServerUrl(source, index, url) {
+    return index === 0 ? DOCS_API_ORIGIN_TOKEN : url;
 }
 /**
  * Projects the application's connection facts into the presentations a page may

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

@@ -1 +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, rfc8414AuthorizationServerMetadataPath, SCIM_SERVICE_BASE_PATH } 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   * The full SCIM base URL an administrator pastes into their identity provider.\n   *\n   * Unlike the endpoints above this one is NOT gated on an observed surface, because SCIM is\n   * configured in the IdP rather than advertised by the application: the base is where traffic\n   * would be pushed, and whether a given organization has enabled provisioning is a tenant setting\n   * the page discusses separately. Derived from `SCIM_SERVICE_BASE_PATH` for the same reason the\n   * others derive from the route map — the engine owns the mount.\n   */\n  SCIM_BASE_URL = 'scimBaseUrl',\n  /** The OAuth issuer a client configures, and checks the discovery document's `issuer` against. */\n  OAUTH_ISSUER = 'oauthIssuer',\n  /**\n   * Where RFC 8414 authorization-server metadata is served.\n   *\n   * Derived with the engine's own `rfc8414AuthorizationServerMetadataPath`, never by appending the\n   * well-known segment to the issuer. The RFC inserts it BETWEEN the host and the issuer's path, so\n   * an issuer of `…/api/v1` publishes at `/.well-known/oauth-authorization-server/api/v1` — the\n   * opposite construction from OIDC discovery. Getting that backwards is not hypothetical: a real\n   * MCP client derived the RFC location, received the SPA shell, and abandoned authorization\n   * without opening a browser. Documentation that showed a hand-built path would be teaching the\n   * shape that failed.\n   */\n  OAUTH_METADATA_URL = 'oauthMetadataUrl',\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      [ApplicationConnectionInlineValue.SCIM_BASE_URL]: `${primaryBaseUrl(named)}${SCIM_SERVICE_BASE_PATH}`,\n      [ApplicationConnectionInlineValue.OAUTH_ISSUER]: `${primaryBaseUrl(named)}${MAIN_API_BASE_PATH}`,\n      [ApplicationConnectionInlineValue.OAUTH_METADATA_URL]: `${primaryBaseUrl(named)}${rfc8414AuthorizationServerMetadataPath(MAIN_API_BASE_PATH)}`,\n    }),\n  };\n}\n"]}
+{"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, rfc8414AuthorizationServerMetadataPath, SCIM_SERVICE_BASE_PATH } 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   * The full SCIM base URL an administrator pastes into their identity provider.\n   *\n   * Unlike the endpoints above this one is NOT gated on an observed surface, because SCIM is\n   * configured in the IdP rather than advertised by the application: the base is where traffic\n   * would be pushed, and whether a given organization has enabled provisioning is a tenant setting\n   * the page discusses separately. Derived from `SCIM_SERVICE_BASE_PATH` for the same reason the\n   * others derive from the route map — the engine owns the mount.\n   */\n  SCIM_BASE_URL = 'scimBaseUrl',\n  /** The OAuth issuer a client configures, and checks the discovery document's `issuer` against. */\n  OAUTH_ISSUER = 'oauthIssuer',\n  /**\n   * Where RFC 8414 authorization-server metadata is served.\n   *\n   * Derived with the engine's own `rfc8414AuthorizationServerMetadataPath`, never by appending the\n   * well-known segment to the issuer. The RFC inserts it BETWEEN the host and the issuer's path, so\n   * an issuer of `…/api/v1` publishes at `/.well-known/oauth-authorization-server/api/v1` — the\n   * opposite construction from OIDC discovery. Getting that backwards is not hypothetical: a real\n   * MCP client derived the RFC location, received the SPA shell, and abandoned authorization\n   * without opening a browser. Documentation that showed a hand-built path would be teaching the\n   * shape that failed.\n   */\n  OAUTH_METADATA_URL = 'oauthMetadataUrl',\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, index) => `| \\`${renderServerUrl(source, index, 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  source.apiServers.forEach((server, index) => {\n    rows.push(`| Base URL${server.description === undefined ? '' : ` (${server.description})`} | \\`${renderServerUrl(source, index, 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 ? UNPUBLISHED_BASE_URL_STAND_IN : DOCS_API_ORIGIN_TOKEN;\n}\n\n/**\n * How the PRIMARY origin is rendered: as a build-time token, never as the origin generation happened\n * to see (#1203).\n *\n * ## The defect\n *\n * A documentation image built for staging shipped 42 occurrences of `http://localhost:4241` — the\n * SCIM base URL an administrator pastes into their identity provider, the MCP and A2A endpoints, and\n * the `servers` of the published API description. Generation resolved this value on a developer\n * machine, and the resolved bytes are committed, so every later build carried that environment's\n * origin whatever it was built for. The CSP got a per-environment regeneration step; the CONTENT got\n * none.\n *\n * ## Why a token rather than regenerating per environment\n *\n * Regenerating the content in the deploy workflow needs a CLI entry point for a companion-owned\n * generation — heavy for a deploy job — and would still leave the committed artifacts describing\n * whoever generated them last. A token makes the generated content environment-INDEPENDENT, which is\n * the honest thing for a committed artifact, and moves the environment decision to the only place\n * that knows it: the image build, which already receives `WILDO_DOCS_API_BASE_URL` as a docker build\n * argument (`ci-workflow-generator.service.ts` declares it for `AppFrontendType.TECH_DOC`).\n *\n * It also covers the static OpenAPI documents, which are served as files and have no runtime to read\n * `customFields` from — the reason the runtime-substitution option cannot be the whole answer.\n *\n * ## Only the PRIMARY origin\n *\n * Additional entries in `apiServers` are explicitly authored per-environment declarations; a reader\n * who lists several is naming them deliberately and each is already correct. The primary is the one\n * every sample interpolates, and the one an image is built FOR.\n */\nexport const DOCS_API_ORIGIN_TOKEN = '__WILDO_DOCS_API_ORIGIN__';\n\n/**\n * Shown when the application publishes no base URL at all. Unchanged by #1203: there is no origin to\n * defer, so the reader is told to substitute their own — which is what this always said.\n */\nexport const UNPUBLISHED_BASE_URL_STAND_IN = 'https://your-environment.example';\n\n/** The primary server renders as the token; any further declared server renders as authored. */\nfunction renderServerUrl(source: ApplicationConnectionDocumentationSource, index: number, url: string): string {\n  return index === 0 ? DOCS_API_ORIGIN_TOKEN : url;\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      [ApplicationConnectionInlineValue.SCIM_BASE_URL]: `${primaryBaseUrl(named)}${SCIM_SERVICE_BASE_PATH}`,\n      [ApplicationConnectionInlineValue.OAUTH_ISSUER]: `${primaryBaseUrl(named)}${MAIN_API_BASE_PATH}`,\n      [ApplicationConnectionInlineValue.OAUTH_METADATA_URL]: `${primaryBaseUrl(named)}${rfc8414AuthorizationServerMetadataPath(MAIN_API_BASE_PATH)}`,\n    }),\n  };\n}\n"]}

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

@@ -0,0 +1,101 @@
+/**
+ * The chapters an APPLICATION authors, joined to the plan that declares them and projected into
+ * publishable units (#874).
+ *
+ * Until this module the portal could say only what the engine wrote or what the companion projected:
+ * a customer could read a page per resource, and nothing about the journeys that cross them, and
+ * the private derivation's own contract said application content stayed absent until the
+ * app-creator owned an accepted authoring artifact. Two accepted artifacts now exist, both
+ * specification FILES accepted by being committed:
+ *
+ * | artifact | owns |
+ * | --- | --- |
+ * | the documentation plan (`documentationPlan`) | each chapter's identity — ref, title, kind, audiences |
+ * | the authored chapters (`documentationChapters`) | each chapter's body, classification, API references |
+ *
+ * This is the join, and it mirrors the framework's own catalogue: authored Markdown joined to a unit
+ * definition by key, with the projector refusing a content set that does not match its definitions.
+ *
+ * ## What is refused, and what is merely withheld
+ *
+ * | condition | outcome | why |
+ * | --- | --- | --- |
+ * | a chapter no plan declares (or no plan at all) | withheld, and reported (`authoredChapterRefsWithoutPlan`) | the plan owns the chapter's title, kind and audiences, so there is nothing true to publish it under — but the body is unfinished work, not a false statement |
+ * | a `RESTRICTED` chapter | withheld by the publication policy (`RESTRICTED_SOURCE`) | the chapter is true, and not for this audience |
+ * | a `DRAFT` / `REVIEW_REQUIRED` chapter | withheld by the policy (`EDITORIAL_NOT_APPROVED`) | the author said it is not ready |
+ * | a planned chapter with no body yet | not published, and reported | unfinished rather than false |
+ * | an API reference the rendered reference does not carry | THROWS at publication | see {@link assertApplicationDocumentationChapterApiReferencesResolve} |
+ *
+ * Refusal is kept to the one case where publishing would state something untrue — a guide telling a
+ * reader to call an operation that does not exist. Everything else is withheld and reported, so it
+ * travels with the artifact and stops nothing (`application-creation-directive.md`).
+ *
+ * Rejected alternative, kept here because it was the first version: REFUSING an unplanned body. It
+ * made one orphaned chapter — a plan ref renamed, a draft written ahead of its plan entry — stop the
+ * whole portal, including the build lane's derived publication step, although withholding that body
+ * publishes nothing untrue.
+ */
+import { type ApplicationDocumentationChapterApiReference, type TechnicalDocumentationApiReferenceTargetV1, type TechnicalDocumentationAuthorizedBundleManifestV1, type TechnicalDocumentationUnitV1 } from '@wildo-ai/saas-specifications/technical-documentation';
+import { type ApiReferenceLinkIndex } from '../../openapi/api-reference-link-index';
+/**
+ * The unit-ref namespace authored chapters live in, and the only place its shape is written.
+ *
+ * A RESERVED engine namespace, like `unit/manages/`: the renderer routes it to `guides/<slug>`, so
+ * an application chooses a chapter's slug but never its URL scheme, and nothing an application names
+ * can land in the engine's own route table.
+ */
+export declare const APPLICATION_DOCUMENTATION_CHAPTER_UNIT_REF_PREFIX = "technical-documentation:unit/guides/";
+/** The portal directory every authored chapter is published under. */
+export declare const APPLICATION_DOCUMENTATION_CHAPTER_ROUTE_DIRECTORY = "guides";
+/** Provenance ref of one authored chapter — the file a reader traces the page back to. */
+export declare const APPLICATION_DOCUMENTATION_CHAPTER_SOURCE_PREFIX = "source:application-chapter:";
+/** `chapter-close-a-deal` → `close-a-deal`: the slug a route and a unit ref are built from. */
+export declare function applicationDocumentationChapterSlug(chapterRef: string): string;
+export declare function applicationDocumentationChapterUnitRef(chapterRef: string): string;
+/**
+ * The portable target one authored API reference names.
+ *
+ * Built with `encodeURIComponent`, exactly as the OpenAPI identity constructor builds the refs it
+ * indexes (`createOpenApiOperationIdentity`) — so an operation named `complete-all` or one carrying a
+ * `:` resolves to the same key on both sides rather than failing on an encoding difference.
+ */
+export declare function applicationDocumentationChapterApiReferenceTarget(reference: ApplicationDocumentationChapterApiReference): TechnicalDocumentationApiReferenceTargetV1;
+export interface ProjectApplicationDocumentationChaptersInput {
+    /** The accepted plan, as the specifications package exports it. Parsed here: the export is untyped at runtime. */
+    readonly plan: unknown;
+    /** The accepted chapter bodies, as the specifications package exports them. Parsed here too. */
+    readonly chapters: unknown;
+}
+export interface ApplicationDocumentationChaptersProjection {
+    /** One unit per authored chapter, unfiltered: the publication policy decides what a reader sees. */
+    readonly units: readonly TechnicalDocumentationUnitV1[];
+    /** Chapters the plan declares whose body nobody has authored yet — reported, never refused. */
+    readonly plannedChapterRefsWithoutBody: readonly string[];
+    /**
+     * Bodies authored under a `chapterRef` the accepted plan does not declare (or with no plan, or a
+     * NOT_APPLICABLE one). Withheld — they have no title, kind or audience to publish under — and
+     * reported, never refused.
+     */
+    readonly authoredChapterRefsWithoutPlan: readonly string[];
+}
+/**
+ * Joins the authored chapters to the plan that declares them. A pure function of its two inputs.
+ * A body the plan does not declare is withheld and reported — see the module table.
+ */
+export declare function projectApplicationDocumentationChapters(input: ProjectApplicationDocumentationChaptersInput): ApplicationDocumentationChaptersProjection;
+/**
+ * Refuses a publication in which an authored chapter cites an API contract the rendered reference
+ * does not carry.
+ *
+ * The engine's own pages DEGRADE such a link to plain text (#472), and for them that is right: the
+ * engine hardcodes targets naming resources an application may switch off, so an absent target there
+ * is a configuration fact. An application's chapter has no such excuse — its author wrote the
+ * reference against THIS application, so an absent target is a typo, a renamed operation or a
+ * removed one, and a guide telling a reader to call an operation that does not exist is exactly the
+ * sentence this portal must never publish. So it fails, naming every dangling reference at once.
+ *
+ * Checked against the PUBLISHED bundle only: a withheld chapter never reaches a reader, and a
+ * restricted one may legitimately cite a contract the public reference omits.
+ */
+export declare function assertApplicationDocumentationChapterApiReferencesResolve(publicBundle: TechnicalDocumentationAuthorizedBundleManifestV1, apiReferenceLinkIndex: ApiReferenceLinkIndex): void;
+//# sourceMappingURL=application-documentation-chapters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"application-documentation-chapters.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-documentation-chapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAYL,KAAK,2CAA2C,EAGhD,KAAK,0CAA0C,EAC/C,KAAK,gDAAgD,EAErD,KAAK,4BAA4B,EAClC,MAAM,uDAAuD,CAAC;AAE/D,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAGhD;;;;;;GAMG;AACH,eAAO,MAAM,iDAAiD,yCAAyC,CAAC;AAExG,sEAAsE;AACtE,eAAO,MAAM,iDAAiD,WAAW,CAAC;AAE1E,0FAA0F;AAC1F,eAAO,MAAM,+CAA+C,gCAAgC,CAAC;AAS7F,+FAA+F;AAC/F,wBAAgB,mCAAmC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAK9E;AAED,wBAAgB,sCAAsC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;GAMG;AACH,wBAAgB,iDAAiD,CAAC,SAAS,EAAE,2CAA2C,GAAG,0CAA0C,CAepK;AAED,MAAM,WAAW,4CAA4C;IAC3D,kHAAkH;IAClH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,0CAA0C;IACzD,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACxD,+FAA+F;IAC/F,QAAQ,CAAC,6BAA6B,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,8BAA8B,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5D;AAED;;;GAGG;AACH,wBAAgB,uCAAuC,CAAC,KAAK,EAAE,4CAA4C,GAAG,0CAA0C,CAoFvJ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yDAAyD,CACvE,YAAY,EAAE,gDAAgD,EAC9D,qBAAqB,EAAE,qBAAqB,GAC3C,IAAI,CAcN"}

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

@@ -0,0 +1,205 @@
+/**
+ * The chapters an APPLICATION authors, joined to the plan that declares them and projected into
+ * publishable units (#874).
+ *
+ * Until this module the portal could say only what the engine wrote or what the companion projected:
+ * a customer could read a page per resource, and nothing about the journeys that cross them, and
+ * the private derivation's own contract said application content stayed absent until the
+ * app-creator owned an accepted authoring artifact. Two accepted artifacts now exist, both
+ * specification FILES accepted by being committed:
+ *
+ * | artifact | owns |
+ * | --- | --- |
+ * | the documentation plan (`documentationPlan`) | each chapter's identity — ref, title, kind, audiences |
+ * | the authored chapters (`documentationChapters`) | each chapter's body, classification, API references |
+ *
+ * This is the join, and it mirrors the framework's own catalogue: authored Markdown joined to a unit
+ * definition by key, with the projector refusing a content set that does not match its definitions.
+ *
+ * ## What is refused, and what is merely withheld
+ *
+ * | condition | outcome | why |
+ * | --- | --- | --- |
+ * | a chapter no plan declares (or no plan at all) | withheld, and reported (`authoredChapterRefsWithoutPlan`) | the plan owns the chapter's title, kind and audiences, so there is nothing true to publish it under — but the body is unfinished work, not a false statement |
+ * | a `RESTRICTED` chapter | withheld by the publication policy (`RESTRICTED_SOURCE`) | the chapter is true, and not for this audience |
+ * | a `DRAFT` / `REVIEW_REQUIRED` chapter | withheld by the policy (`EDITORIAL_NOT_APPROVED`) | the author said it is not ready |
+ * | a planned chapter with no body yet | not published, and reported | unfinished rather than false |
+ * | an API reference the rendered reference does not carry | THROWS at publication | see {@link assertApplicationDocumentationChapterApiReferencesResolve} |
+ *
+ * Refusal is kept to the one case where publishing would state something untrue — a guide telling a
+ * reader to call an operation that does not exist. Everything else is withheld and reported, so it
+ * travels with the artifact and stops nothing (`application-creation-directive.md`).
+ *
+ * Rejected alternative, kept here because it was the first version: REFUSING an unplanned body. It
+ * made one orphaned chapter — a plan ref renamed, a draft written ahead of its plan entry — stop the
+ * whole portal, including the build lane's derived publication step, although withholding that body
+ * publishes nothing untrue.
+ */
+import { ApplicationDocumentationPlanDisposition, TechnicalDocumentationAccessClass, TechnicalDocumentationApiReferenceSection, TechnicalDocumentationApiReferenceTargetKind, TechnicalDocumentationEditorialStatus, TechnicalDocumentationLinkKind, TechnicalDocumentationSourceOwnership, DOCUMENTATION_CHAPTER_REF_PREFIX, ApplicationDocumentationChapterSetSchema, ApplicationDocumentationPlanSchema, createTechnicalDocumentationUnitV1, } from '@wildo-ai/saas-specifications/technical-documentation';
+import { getTechnicalDocumentationApiReferenceTargetAvailability, TechnicalDocumentationApiReferenceTargetAvailability, } from '../../openapi/api-reference-link-index.js';
+import { parseTechnicalDocumentationUnitMarkdown } from './technical-documentation-engine-content-bundle.js';
+/**
+ * The unit-ref namespace authored chapters live in, and the only place its shape is written.
+ *
+ * A RESERVED engine namespace, like `unit/manages/`: the renderer routes it to `guides/<slug>`, so
+ * an application chooses a chapter's slug but never its URL scheme, and nothing an application names
+ * can land in the engine's own route table.
+ */
+export const APPLICATION_DOCUMENTATION_CHAPTER_UNIT_REF_PREFIX = 'technical-documentation:unit/guides/';
+/** The portal directory every authored chapter is published under. */
+export const APPLICATION_DOCUMENTATION_CHAPTER_ROUTE_DIRECTORY = 'guides';
+/** Provenance ref of one authored chapter — the file a reader traces the page back to. */
+export const APPLICATION_DOCUMENTATION_CHAPTER_SOURCE_PREFIX = 'source:application-chapter:';
+/**
+ * The only version an authored chapter carries. A chapter is versioned by git, not by a counter in
+ * the file (`one-source-of-truth.md`); the unit schema requires a positive version, and 1 states
+ * that nothing else is being claimed.
+ */
+const APPLICATION_DOCUMENTATION_CHAPTER_SOURCE_VERSION = 1;
+/** `chapter-close-a-deal` → `close-a-deal`: the slug a route and a unit ref are built from. */
+export function applicationDocumentationChapterSlug(chapterRef) {
+    if (!chapterRef.startsWith(DOCUMENTATION_CHAPTER_REF_PREFIX)) {
+        throw new Error(`documentation chapter ref ${chapterRef} does not start with ${DOCUMENTATION_CHAPTER_REF_PREFIX}`);
+    }
+    return chapterRef.slice(DOCUMENTATION_CHAPTER_REF_PREFIX.length);
+}
+export function applicationDocumentationChapterUnitRef(chapterRef) {
+    return `${APPLICATION_DOCUMENTATION_CHAPTER_UNIT_REF_PREFIX}${applicationDocumentationChapterSlug(chapterRef)}`;
+}
+/**
+ * The portable target one authored API reference names.
+ *
+ * Built with `encodeURIComponent`, exactly as the OpenAPI identity constructor builds the refs it
+ * indexes (`createOpenApiOperationIdentity`) — so an operation named `complete-all` or one carrying a
+ * `:` resolves to the same key on both sides rather than failing on an encoding difference.
+ */
+export function applicationDocumentationChapterApiReferenceTarget(reference) {
+    const resourceRef = `technical-documentation:resource/${encodeURIComponent(reference.resource)}`;
+    // Omitted means the public API reference, which is where almost every contract a guide cites lives.
+    const section = reference.section ?? TechnicalDocumentationApiReferenceSection.API_REFERENCE;
+    return reference.operation === undefined
+        ? {
+            section,
+            kind: TechnicalDocumentationApiReferenceTargetKind.RESOURCE,
+            resourceRef,
+        }
+        : {
+            section,
+            kind: TechnicalDocumentationApiReferenceTargetKind.OPERATION_FAMILY,
+            operationFamilyRef: `${resourceRef}/operation-family/${encodeURIComponent(reference.operation)}`,
+        };
+}
+/**
+ * Joins the authored chapters to the plan that declares them. A pure function of its two inputs.
+ * A body the plan does not declare is withheld and reported — see the module table.
+ */
+export function projectApplicationDocumentationChapters(input) {
+    const chapters = input.chapters === undefined
+        ? {}
+        : ApplicationDocumentationChapterSetSchema.parse(input.chapters);
+    const plan = input.plan === undefined
+        ? undefined
+        : ApplicationDocumentationPlanSchema.parse(input.plan);
+    const plannedChapters = plan === undefined || plan.disposition === ApplicationDocumentationPlanDisposition.NOT_APPLICABLE ? [] : plan.chapters;
+    const plannedByRef = new Map(plannedChapters.map((chapter) => [chapter.chapterRef, chapter]));
+    const authoredChapterRefsWithoutPlan = Object.keys(chapters).filter((chapterRef) => !plannedByRef.has(chapterRef)).sort();
+    const units = Object.entries(chapters)
+        .filter(([chapterRef]) => plannedByRef.has(chapterRef))
+        .sort(([left], [right]) => left.localeCompare(right, 'en-US'))
+        .map(([chapterRef, chapter]) => {
+        const planned = plannedByRef.get(chapterRef);
+        const unitRef = applicationDocumentationChapterUnitRef(chapterRef);
+        const slug = applicationDocumentationChapterSlug(chapterRef);
+        const parsed = parseTechnicalDocumentationUnitMarkdown(`# ${planned.title}\n\n${chapter.body}`, unitRef);
+        // A related chapter the plan does not declare is withheld above, so there is no page to link to.
+        const relatedLinks = chapter.relatedChapterRefs
+            .filter((relatedChapterRef) => plannedByRef.has(relatedChapterRef))
+            .map((relatedChapterRef) => ({
+            linkRef: `technical-documentation:link/guides-${slug}-to-${applicationDocumentationChapterSlug(relatedChapterRef)}`,
+            kind: TechnicalDocumentationLinkKind.UNIT,
+            // Filtered to planned chapters just above, so the title is always present.
+            label: plannedByRef.get(relatedChapterRef).title,
+            targetUnitRef: applicationDocumentationChapterUnitRef(relatedChapterRef),
+            targetRef: null,
+            externalUrl: null,
+            apiReferenceTarget: null,
+        }));
+        const apiReferenceLinks = chapter.apiReferences.map((reference, index) => ({
+            linkRef: `technical-documentation:link/guides-${slug}-api-reference-${String(index + 1).padStart(2, '0')}`,
+            kind: TechnicalDocumentationLinkKind.API_REFERENCE,
+            label: reference.label,
+            targetUnitRef: null,
+            targetRef: null,
+            externalUrl: null,
+            apiReferenceTarget: applicationDocumentationChapterApiReferenceTarget(reference),
+        }));
+        return createTechnicalDocumentationUnitV1({
+            schemaVersion: 1,
+            unitRef,
+            unitVersion: 1,
+            kind: planned.kind,
+            readerAudiences: [...planned.readerAudiences],
+            title: parsed.title,
+            summary: parsed.summary,
+            sections: parsed.sections.map((section, index) => ({
+                sectionRef: `technical-documentation:section/guides-${slug}-${index + 1}`,
+                heading: section.heading,
+                bodyMarkdown: section.bodyMarkdown,
+            })),
+            links: [...relatedLinks, ...apiReferenceLinks],
+            /*
+             * ONE provenance row, carrying the author's own classification. That row is what the
+             * publication policy reads: a `RESTRICTED` chapter is suppressed with `RESTRICTED_SOURCE`
+             * by the same rule that suppresses any unit derived from a restricted source, so there is
+             * no second, chapter-specific gate to drift from the first.
+             */
+            provenance: [{
+                    sourceRef: `${APPLICATION_DOCUMENTATION_CHAPTER_SOURCE_PREFIX}${chapterRef}`,
+                    ownership: TechnicalDocumentationSourceOwnership.APPLICATION_AUTHORED,
+                    classification: chapter.classification,
+                    sourceVersion: APPLICATION_DOCUMENTATION_CHAPTER_SOURCE_VERSION,
+                    sourceAnchorRef: null,
+                }],
+            applicabilityRequirements: [...chapter.applicabilityRequirements],
+            accessClass: TechnicalDocumentationAccessClass.PUBLIC,
+            editorialStatus: chapter.editorialStatus ?? TechnicalDocumentationEditorialStatus.APPROVED,
+            assetRequests: [],
+        });
+    });
+    return {
+        units,
+        plannedChapterRefsWithoutBody: plannedChapters
+            .map((chapter) => chapter.chapterRef)
+            .filter((chapterRef) => !(chapterRef in chapters))
+            .sort(),
+        authoredChapterRefsWithoutPlan,
+    };
+}
+/**
+ * Refuses a publication in which an authored chapter cites an API contract the rendered reference
+ * does not carry.
+ *
+ * The engine's own pages DEGRADE such a link to plain text (#472), and for them that is right: the
+ * engine hardcodes targets naming resources an application may switch off, so an absent target there
+ * is a configuration fact. An application's chapter has no such excuse — its author wrote the
+ * reference against THIS application, so an absent target is a typo, a renamed operation or a
+ * removed one, and a guide telling a reader to call an operation that does not exist is exactly the
+ * sentence this portal must never publish. So it fails, naming every dangling reference at once.
+ *
+ * Checked against the PUBLISHED bundle only: a withheld chapter never reaches a reader, and a
+ * restricted one may legitimately cite a contract the public reference omits.
+ */
+export function assertApplicationDocumentationChapterApiReferencesResolve(publicBundle, apiReferenceLinkIndex) {
+    const dangling = publicBundle.units
+        .filter((unit) => unit.unitRef.startsWith(APPLICATION_DOCUMENTATION_CHAPTER_UNIT_REF_PREFIX))
+        .flatMap((unit) => unit.links
+        .filter((link) => link.kind === TechnicalDocumentationLinkKind.API_REFERENCE && link.apiReferenceTarget !== null)
+        .filter((link) => getTechnicalDocumentationApiReferenceTargetAvailability(apiReferenceLinkIndex, link.apiReferenceTarget)
+        === TechnicalDocumentationApiReferenceTargetAvailability.UNAVAILABLE)
+        .map((link) => `${unit.unitRef} → "${link.label}" (${JSON.stringify(link.apiReferenceTarget)})`));
+    if (dangling.length > 0) {
+        throw new Error(`authored documentation chapter(s) cite API contracts this application's API reference does not publish: ${dangling.join('; ')}. `
+            + 'Correct the resource or operation name in specifications/src/technical-documentation/index.ts.');
+    }
+}
+//# sourceMappingURL=application-documentation-chapters.js.map