@wildo-ai/saas-technical-doc 1.1.1

package/LICENSE

@@ -0,0 +1,34 @@
+Copyright (c) 2026 P2C Consulting, s.à r.l.-S
+RCS Luxembourg B307591
+6C, Porte de France, L-4360 Esch-sur-Alzette, Luxembourg
+
+All rights reserved.
+
+This software and its accompanying materials (the "Software") are the
+confidential and proprietary property of P2C Consulting, s.à r.l.-S (the
+"Licensor"). The Software is made available for viewing only. No licence,
+right, or permission of any kind is granted by its publication or by its
+availability on any package registry or source repository.
+
+Without the Licensor's prior written permission, you may not use, copy,
+reproduce, modify, adapt, translate, merge, publish, distribute, sublicense,
+sell, host, or create derivative works of the Software, in whole or in part,
+nor use it to provide a service to any third party.
+
+Publication of the Software in any public registry is for distribution to
+authorised recipients and for technical evaluation of its packaging only. It
+does not place the Software in the public domain, does not constitute an open
+source release, and does not waive any right of the Licensor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Third-party components distributed with the Software remain governed by their
+own licences.
+
+Contact: P2C Consulting, s.à r.l.-S, 6C, Porte de France, L-4360
+Esch-sur-Alzette, Luxembourg.

package/dist/esm/.builder.pid

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "writerPid": 95135,
+  "orchestratorPid": 94847,
+  "orchestratorSessionId": null,
+  "orchestratorStartedAt": "Mon Aug 31 09:18:19 2026",
+  "distDirectory": "/Users/paulcayon/Projects/Wildo.ai/dev/wildo-ai/engine/saas-technical-doc/dist/esm",
+  "acquiredAt": "2026-08-31T07:18:20.748Z"
+}

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

@@ -0,0 +1,9 @@
+import { emitCspArtifacts as emitPlatformCspArtifacts, resolveCspPolicy as resolvePlatformCspPolicy, rewriteNginxCspMarkerPairs as rewritePlatformNginxCspMarkerPairs, rewriteNginxCspMarkerPairsString as rewritePlatformNginxCspMarkerPairsString, type CspEmitArtifacts, type ResolvedCspDirectiveMap, type ResolvedCspPolicy, type ResolveCspPolicyInput, type RewriteNginxResult } from '@wildo-ai/platform-config-lib';
+export type { CspEmitArtifacts, ResolvedCspDirectiveMap, ResolvedCspPolicy, ResolveCspPolicyInput, RewriteNginxResult, };
+export declare const NGINX_CSP_BEGIN_MARKER = "# >>> wildo csp begin";
+export declare const NGINX_CSP_END_MARKER = "# <<< wildo csp end";
+export declare const resolveCspPolicy: typeof resolvePlatformCspPolicy;
+export declare const emitCspArtifacts: typeof emitPlatformCspArtifacts;
+export declare const rewriteNginxCspMarkerPairs: typeof rewritePlatformNginxCspMarkerPairs;
+export declare const rewriteNginxCspMarkerPairsString: typeof rewritePlatformNginxCspMarkerPairsString;
+//# sourceMappingURL=csp-emit.d.ts.map

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

@@ -0,0 +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"}

package/dist/esm/build/csp-emit.js

@@ -0,0 +1,8 @@
+import { emitCspArtifacts as emitPlatformCspArtifacts, NGINX_CSP_BEGIN_MARKER as PLATFORM_NGINX_CSP_BEGIN_MARKER, NGINX_CSP_END_MARKER as PLATFORM_NGINX_CSP_END_MARKER, resolveCspPolicy as resolvePlatformCspPolicy, rewriteNginxCspMarkerPairs as rewritePlatformNginxCspMarkerPairs, rewriteNginxCspMarkerPairsString as rewritePlatformNginxCspMarkerPairsString, } from '@wildo-ai/platform-config-lib';
+export const NGINX_CSP_BEGIN_MARKER = PLATFORM_NGINX_CSP_BEGIN_MARKER;
+export const NGINX_CSP_END_MARKER = PLATFORM_NGINX_CSP_END_MARKER;
+export const resolveCspPolicy = resolvePlatformCspPolicy;
+export const emitCspArtifacts = emitPlatformCspArtifacts;
+export const rewriteNginxCspMarkerPairs = rewritePlatformNginxCspMarkerPairs;
+export const rewriteNginxCspMarkerPairsString = rewritePlatformNginxCspMarkerPairsString;
+//# sourceMappingURL=csp-emit.js.map

package/dist/esm/build/csp-emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csp-emit.js","sourceRoot":"","sources":["../../../../src/build/csp-emit.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,IAAI,wBAAwB,EAC5C,sBAAsB,IAAI,+BAA+B,EACzD,oBAAoB,IAAI,6BAA6B,EACrD,gBAAgB,IAAI,wBAAwB,EAC5C,0BAA0B,IAAI,kCAAkC,EAChE,gCAAgC,IAAI,wCAAwC,GAM7E,MAAM,+BAA+B,CAAC;AAUvC,MAAM,CAAC,MAAM,sBAAsB,GAAG,+BAA+B,CAAC;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAG,6BAA6B,CAAC;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AACzD,MAAM,CAAC,MAAM,0BAA0B,GAAG,kCAAkC,CAAC;AAC7E,MAAM,CAAC,MAAM,gCAAgC,GAAG,wCAAwC,CAAC","sourcesContent":["import {\n  emitCspArtifacts as emitPlatformCspArtifacts,\n  NGINX_CSP_BEGIN_MARKER as PLATFORM_NGINX_CSP_BEGIN_MARKER,\n  NGINX_CSP_END_MARKER as PLATFORM_NGINX_CSP_END_MARKER,\n  resolveCspPolicy as resolvePlatformCspPolicy,\n  rewriteNginxCspMarkerPairs as rewritePlatformNginxCspMarkerPairs,\n  rewriteNginxCspMarkerPairsString as rewritePlatformNginxCspMarkerPairsString,\n  type CspEmitArtifacts,\n  type ResolvedCspDirectiveMap,\n  type ResolvedCspPolicy,\n  type ResolveCspPolicyInput,\n  type RewriteNginxResult,\n} from '@wildo-ai/platform-config-lib';\n\nexport type {\n  CspEmitArtifacts,\n  ResolvedCspDirectiveMap,\n  ResolvedCspPolicy,\n  ResolveCspPolicyInput,\n  RewriteNginxResult,\n};\n\nexport const NGINX_CSP_BEGIN_MARKER = PLATFORM_NGINX_CSP_BEGIN_MARKER;\nexport const NGINX_CSP_END_MARKER = PLATFORM_NGINX_CSP_END_MARKER;\nexport const resolveCspPolicy = resolvePlatformCspPolicy;\nexport const emitCspArtifacts = emitPlatformCspArtifacts;\nexport const rewriteNginxCspMarkerPairs = rewritePlatformNginxCspMarkerPairs;\nexport const rewriteNginxCspMarkerPairsString = rewritePlatformNginxCspMarkerPairsString;\n"]}

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

@@ -0,0 +1,9 @@
+/**
+ * Re-export of the canonical frontend-providers loader helpers.
+ * The implementation lives in `@wildo-ai/platform-config-lib`
+ * (`provider-runtime-artifacts.ts`) so the website + tech-doc + any
+ * future build-time consumer share one source of truth — see the
+ * dedup-rationale JSDoc on `loadMaterializedFrontendProviders` there.
+ */
+export { loadMaterializedFrontendProviders, resolveFrontendServicesArtifactPath, } from '@wildo-ai/platform-config-lib';
+//# sourceMappingURL=load-materialized-frontend-providers.d.ts.map

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

@@ -0,0 +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"}

package/dist/esm/build/load-materialized-frontend-providers.js

@@ -0,0 +1,9 @@
+/**
+ * Re-export of the canonical frontend-providers loader helpers.
+ * The implementation lives in `@wildo-ai/platform-config-lib`
+ * (`provider-runtime-artifacts.ts`) so the website + tech-doc + any
+ * future build-time consumer share one source of truth — see the
+ * dedup-rationale JSDoc on `loadMaterializedFrontendProviders` there.
+ */
+export { loadMaterializedFrontendProviders, resolveFrontendServicesArtifactPath, } from '@wildo-ai/platform-config-lib';
+//# sourceMappingURL=load-materialized-frontend-providers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load-materialized-frontend-providers.js","sourceRoot":"","sources":["../../../../src/build/load-materialized-frontend-providers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iCAAiC,EACjC,mCAAmC,GACpC,MAAM,+BAA+B,CAAC","sourcesContent":["/**\n * Re-export of the canonical frontend-providers loader helpers.\n * The implementation lives in `@wildo-ai/platform-config-lib`\n * (`provider-runtime-artifacts.ts`) so the website + tech-doc + any\n * future build-time consumer share one source of truth — see the\n * dedup-rationale JSDoc on `loadMaterializedFrontendProviders` there.\n */\nexport {\n  loadMaterializedFrontendProviders,\n  resolveFrontendServicesArtifactPath,\n} from '@wildo-ai/platform-config-lib';\n"]}

package/dist/esm/companion/application-documentation/application-organization-role-documentation.d.ts

@@ -0,0 +1,66 @@
+import { ResourcePrimaryScope } from '@wildo-ai/saas-models';
+import type { ApplicationOrganizationRolesDocumentationFact } from './technical-documentation-engine-content-bundle';
+export declare const APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_REF: "source:companion-projection:organization-roles";
+/** Advances when this projection's shape changes; it is the fact's version wherever provenance cites it. */
+export declare const APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_VERSION = 1;
+/** Minimal application/engine role specification needed by consumer documentation. */
+export interface ApplicationRoleDocumentationSource {
+    readonly ref: string;
+    readonly purpose: string | null;
+    readonly businessRole: string | null;
+    readonly authorityBoundary: string | null;
+    readonly useWhen: string | null;
+    readonly avoidWhen: string | null;
+    readonly businessConstraints: readonly string[] | null;
+}
+/**
+ * Application-independent organization-role projection before UI labels are
+ * joined. The introspection subprocess can safely emit this JSON-only shape;
+ * the parent companion later joins the application's primary-locale labels.
+ */
+export interface ApplicationOrganizationRoleDocumentationSource {
+    readonly role: string;
+    readonly inheritFrom: string | null;
+    readonly purpose: string;
+    readonly businessRole: string | null;
+    readonly authorityBoundary: string;
+    readonly useWhen: string;
+    readonly avoidWhen: string;
+    readonly businessConstraints: readonly string[];
+}
+/** Complete consumer-visible role documentation after the application label join. */
+export interface ApplicationOrganizationRoleDocumentation extends ApplicationOrganizationRoleDocumentationSource {
+    readonly label: string;
+    readonly description: string;
+}
+interface ApplicationRoleConfigurationProjectionInput {
+    readonly role?: string;
+    readonly inheritFrom?: string;
+    readonly relatedPrimaryScope: ResourcePrimaryScope;
+}
+/**
+ * Index companion-exported role specifications by their runtime role token.
+ * Engine and application-defined roles intentionally share this namespace.
+ */
+export declare function indexApplicationRoleDocumentationSources(roleSpecifications: Record<string, unknown> | undefined): ReadonlyMap<string, ApplicationRoleDocumentationSource>;
+/**
+ * Resolve every framework and application-defined organization role from the
+ * application's merged runtime registry and authored role specifications.
+ * Application-scoped roles are deliberately excluded from this organization
+ * administration reference.
+ */
+export declare function projectApplicationOrganizationRoleDocumentationSources(customRoles: Readonly<Record<string, ApplicationRoleConfigurationProjectionInput>> | undefined, roleSpecsByRef: ReadonlyMap<string, ApplicationRoleDocumentationSource>): readonly ApplicationOrganizationRoleDocumentationSource[];
+/**
+ * Join role semantics to the exact primary-locale labels shown by the
+ * application. Missing values fail closed: publishing a guessed label would
+ * make the guide disagree with member-management and role-picker UI.
+ */
+export declare function resolveApplicationOrganizationRoleDocumentation(roles: readonly ApplicationOrganizationRoleDocumentationSource[], primaryLocaleLabels: Readonly<Record<string, string>>): readonly ApplicationOrganizationRoleDocumentation[];
+/**
+ * Materialize the reusable Markdown fact consumed by the Roles and permissions
+ * topic. This function knows no application identity: different applications
+ * receive different role inputs and therefore different facts.
+ */
+export declare function createApplicationOrganizationRolesDocumentationFact(roles: readonly ApplicationOrganizationRoleDocumentation[]): ApplicationOrganizationRolesDocumentationFact;
+export {};
+//# sourceMappingURL=application-organization-role-documentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"application-organization-role-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-organization-role-documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,6CAA6C,EAAE,MAAM,iDAAiD,CAAC;AAErH,eAAO,MAAM,uDAAuD,EAAG,gDAAyD,CAAC;AACjI,4GAA4G;AAC5G,eAAO,MAAM,2DAA2D,IAAI,CAAC;AAE7E,sFAAsF;AACtF,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,8CAA8C;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,qFAAqF;AACrF,MAAM,WAAW,wCAAyC,SAAQ,8CAA8C;IAC9G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,UAAU,2CAA2C;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,oBAAoB,CAAC;CACpD;AAED;;;GAGG;AACH,wBAAgB,wCAAwC,CACtD,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACtD,WAAW,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAkBzD;AAED;;;;;GAKG;AACH,wBAAgB,sDAAsD,CACpE,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2CAA2C,CAAC,CAAC,GAAG,SAAS,EAC9F,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,kCAAkC,CAAC,GACtE,SAAS,8CAA8C,EAAE,CA8C3D;AAED;;;;GAIG;AACH,wBAAgB,+CAA+C,CAC7D,KAAK,EAAE,SAAS,8CAA8C,EAAE,EAChE,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpD,SAAS,wCAAwC,EAAE,CAMrD;AAED;;;;GAIG;AACH,wBAAgB,mDAAmD,CACjE,KAAK,EAAE,SAAS,wCAAwC,EAAE,GACzD,6CAA6C,CAgC/C"}

package/dist/esm/companion/application-documentation/application-organization-role-documentation.js

@@ -0,0 +1,195 @@
+import { CORE_ORG_ROLES, DEFAULT_ORGANIZATION_ROLES, ResourcePrimaryScope, } from '@wildo-ai/saas-models';
+export const APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:organization-roles';
+/** Advances when this projection's shape changes; it is the fact's version wherever provenance cites it. */
+export const APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_VERSION = 1;
+/**
+ * Index companion-exported role specifications by their runtime role token.
+ * Engine and application-defined roles intentionally share this namespace.
+ */
+export function indexApplicationRoleDocumentationSources(roleSpecifications) {
+    const result = new Map();
+    for (const candidate of Object.values(roleSpecifications ?? {})) {
+        if (!isPlainObject(candidate) || typeof candidate.ref !== 'string' || candidate.ref.length === 0)
+            continue;
+        if (result.has(candidate.ref)) {
+            throw new Error(`application organization-role projector: duplicate role specification for '${candidate.ref}'`);
+        }
+        result.set(candidate.ref, {
+            ref: candidate.ref,
+            purpose: nonEmptyStringOrNull(candidate.purpose),
+            businessRole: nonEmptyStringOrNull(candidate.businessRole),
+            authorityBoundary: nonEmptyStringOrNull(candidate.authorityBoundary),
+            useWhen: nonEmptyStringOrNull(candidate.useWhen),
+            avoidWhen: nonEmptyStringOrNull(candidate.avoidWhen),
+            businessConstraints: nonEmptyStringArrayOrNull(candidate.businessConstraints),
+        });
+    }
+    return result;
+}
+/**
+ * Resolve every framework and application-defined organization role from the
+ * application's merged runtime registry and authored role specifications.
+ * Application-scoped roles are deliberately excluded from this organization
+ * administration reference.
+ */
+export function projectApplicationOrganizationRoleDocumentationSources(customRoles, roleSpecsByRef) {
+    const configured = new Map();
+    for (const config of Object.values(DEFAULT_ORGANIZATION_ROLES)) {
+        if (typeof config.role !== 'string' || config.role.length === 0) {
+            throw new Error('application organization-role projector: framework organization role configuration has no role token');
+        }
+        configured.set(config.role, { ...config, role: config.role });
+    }
+    for (const config of Object.values(customRoles ?? {})) {
+        if (typeof config.role !== 'string' || config.role.length === 0) {
+            throw new Error('application organization-role projector: application organization role configuration has no role token');
+        }
+        if (configured.has(config.role)) {
+            throw new Error(`application organization-role projector: application role '${config.role}' collides with a framework organization role`);
+        }
+        configured.set(config.role, { ...config, role: config.role });
+    }
+    return Object.freeze([...configured.values()]
+        .filter((config) => config.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS)
+        .map((config) => {
+        const specification = roleSpecsByRef.get(config.role);
+        if (specification === undefined
+            || specification.purpose === null
+            || specification.authorityBoundary === null
+            || specification.useWhen === null
+            || specification.avoidWhen === null
+            || specification.businessConstraints === null) {
+            throw new Error(`application organization-role projector: organization role '${config.role}' has no companion-exported role specification with complete consumer guidance`);
+        }
+        return Object.freeze({
+            role: config.role,
+            inheritFrom: config.inheritFrom ?? null,
+            purpose: specification.purpose,
+            businessRole: specification.businessRole,
+            authorityBoundary: specification.authorityBoundary,
+            useWhen: specification.useWhen,
+            avoidWhen: specification.avoidWhen,
+            businessConstraints: specification.businessConstraints,
+        });
+    })
+        .sort((left, right) => left.role.localeCompare(right.role, 'en-US')));
+}
+/**
+ * Join role semantics to the exact primary-locale labels shown by the
+ * application. Missing values fail closed: publishing a guessed label would
+ * make the guide disagree with member-management and role-picker UI.
+ */
+export function resolveApplicationOrganizationRoleDocumentation(roles, primaryLocaleLabels) {
+    return Object.freeze(roles.map((role) => Object.freeze({
+        ...role,
+        label: requiredRoleLabel(primaryLocaleLabels, role.role, 'label'),
+        description: requiredRoleLabel(primaryLocaleLabels, role.role, 'description'),
+    })));
+}
+/**
+ * Materialize the reusable Markdown fact consumed by the Roles and permissions
+ * topic. This function knows no application identity: different applications
+ * receive different role inputs and therefore different facts.
+ */
+export function createApplicationOrganizationRolesDocumentationFact(roles) {
+    if (roles.length === 0)
+        throw new Error('technical documentation requires at least one resolved organization role');
+    if (new Set(roles.map((role) => role.role)).size !== roles.length) {
+        throw new Error('technical documentation received duplicate resolved organization roles');
+    }
+    const roleByIdentifier = new Map(roles.map((role) => [role.role, role]));
+    const hierarchyDepthByRole = new Map(roles.map((role) => [role.role, hierarchyDepth(role, roleByIdentifier)]));
+    // Readers compare authority from broadest to narrowest. Derive that order
+    // from the actual inheritance chain; sibling branches use visible labels and
+    // stable role tokens only as deterministic tie-breakers.
+    const canonicalRoles = [...roles].sort((left, right) => hierarchyDepthByRole.get(right.role) - hierarchyDepthByRole.get(left.role)
+        || left.label.localeCompare(right.label, 'en-US')
+        || left.role.localeCompare(right.role, 'en-US'));
+    const roleSections = canonicalRoles.map((role) => {
+        const inheritedRole = role.inheritFrom === null ? undefined : roleByIdentifier.get(role.inheritFrom);
+        const inheritance = role.inheritFrom === null
+            ? 'This role does not inherit another organization role.'
+            : `This role includes the permissions of **${markdownText(inheritedRole?.label ?? role.inheritFrom)}** (${inlineCode(role.inheritFrom)}).`;
+        const limits = [role.avoidWhen, ...role.businessConstraints]
+            .map((constraint) => `- ${markdownProse(constraint)}`)
+            .join('\n');
+        return `### ${markdownText(role.label)}\n\n${markdownText(role.description)}\n\n- **Where it applies:** ${markdownProse(role.authorityBoundary)}\n- **Inherited access:** ${inheritance}\n- **Technical identifier:** ${inlineCode(role.role)}\n\n#### Can do\n\n${markdownProse(role.purpose)}\n\n${markdownProse(role.useWhen)}\n\n#### Cannot do\n\n${limits}\n\n#### Can assign\n\n${roleAssignmentMarkdown(role, roleByIdentifier)}`;
+    }).join('\n\n');
+    return Object.freeze({
+        sourceRef: APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_REF,
+        markdown: `These are all the organization roles available in this application. Their names and short descriptions match the application's primary-language interface; the technical identifier is included so you can recognize the same role in an access request, audit record, or API response.\n\n${roleSections}\n\n> **How inherited access works:** when one role includes another, it receives the included role’s permissions as well as its own. The reverse is not true: assigning the included role never grants the higher role.`,
+        sourceVersion: APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_VERSION,
+    });
+}
+function hierarchyDepth(role, roleByIdentifier, ancestors = new Set()) {
+    if (role.inheritFrom === null)
+        return 0;
+    if (ancestors.has(role.role)) {
+        throw new Error(`technical documentation organization-role hierarchy contains a cycle at ${role.role}`);
+    }
+    const inheritedRole = roleByIdentifier.get(role.inheritFrom);
+    if (inheritedRole === undefined) {
+        throw new Error(`technical documentation organization role ${role.role} inherits absent role ${role.inheritFrom}`);
+    }
+    return 1 + hierarchyDepth(inheritedRole, roleByIdentifier, new Set([...ancestors, role.role]));
+}
+/**
+ * Explain the standard organization-role assignment ceiling from the exact
+ * application role graph. This deliberately does not flatten custom roles into
+ * a total order: sibling custom branches are outside one another's ceiling.
+ * A role must also inherit the administrator gate before it can use the
+ * standard membership and unit-assignment controls at all.
+ */
+function roleAssignmentMarkdown(role, roleByIdentifier) {
+    const effectiveRoles = [];
+    let current = role;
+    const visited = new Set();
+    while (current !== undefined) {
+        if (visited.has(current.role)) {
+            throw new Error(`technical documentation organization-role hierarchy contains a cycle at ${current.role}`);
+        }
+        visited.add(current.role);
+        effectiveRoles.push(current);
+        current = current.inheritFrom === null ? undefined : roleByIdentifier.get(current.inheritFrom);
+    }
+    if (!effectiveRoles.some((candidate) => candidate.role === CORE_ORG_ROLES.ORG_ADMIN)) {
+        return 'This role cannot use the standard organization-membership or organization-unit assignment controls. It therefore cannot assign an organization or unit role through those controls.';
+    }
+    const assignableRoles = effectiveRoles
+        .map((candidate) => `**${markdownText(candidate.label)}** (${inlineCode(candidate.role)})`)
+        .join(', ');
+    return `Through the standard membership and unit-assignment controls, this role can assign: ${assignableRoles}. It cannot assign a role outside this inheritance chain unless the person also holds another organization-wide role whose chain includes it.`;
+}
+function requiredRoleLabel(labels, role, field) {
+    const key = `roles.${role}.${field}`;
+    const value = labels[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`application organization-role documentation requires primary-locale label '${key}'; generate the application's role labels before publishing documentation`);
+    }
+    return value.trim();
+}
+function nonEmptyStringOrNull(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function nonEmptyStringArrayOrNull(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const normalized = value.map(nonEmptyStringOrNull);
+    return normalized.every((entry) => entry !== null)
+        ? Object.freeze(normalized)
+        : null;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function markdownText(value) {
+    return value.replaceAll(/\s+/g, ' ').trim().replaceAll('\\', '\\\\').replaceAll(/([`*_[\]<>#|])/g, '\\$1');
+}
+/** Role specifications intentionally author small inline-Markdown semantics. */
+function markdownProse(value) {
+    return value.replaceAll(/\s+/g, ' ').trim();
+}
+function inlineCode(value) {
+    return `\`${value.replaceAll('`', '&#96;')}\``;
+}
+//# sourceMappingURL=application-organization-role-documentation.js.map

package/dist/esm/companion/application-documentation/application-organization-role-documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-organization-role-documentation.js","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-organization-role-documentation.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  CORE_ORG_ROLES,\n  DEFAULT_ORGANIZATION_ROLES,\n  ResourcePrimaryScope,\n} from '@wildo-ai/saas-models';\nimport {\n} from '@wildo-ai/saas-specifications/technical-documentation';\n\nimport type { ApplicationOrganizationRolesDocumentationFact } from './technical-documentation-engine-content-bundle';\n\nexport const APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:organization-roles' as const;\n/** Advances when this projection's shape changes; it is the fact's version wherever provenance cites it. */\nexport const APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_VERSION = 1;\n\n/** Minimal application/engine role specification needed by consumer documentation. */\nexport interface ApplicationRoleDocumentationSource {\n  readonly ref: string;\n  readonly purpose: string | null;\n  readonly businessRole: string | null;\n  readonly authorityBoundary: string | null;\n  readonly useWhen: string | null;\n  readonly avoidWhen: string | null;\n  readonly businessConstraints: readonly string[] | null;\n}\n\n/**\n * Application-independent organization-role projection before UI labels are\n * joined. The introspection subprocess can safely emit this JSON-only shape;\n * the parent companion later joins the application's primary-locale labels.\n */\nexport interface ApplicationOrganizationRoleDocumentationSource {\n  readonly role: string;\n  readonly inheritFrom: string | null;\n  readonly purpose: string;\n  readonly businessRole: string | null;\n  readonly authorityBoundary: string;\n  readonly useWhen: string;\n  readonly avoidWhen: string;\n  readonly businessConstraints: readonly string[];\n}\n\n/** Complete consumer-visible role documentation after the application label join. */\nexport interface ApplicationOrganizationRoleDocumentation extends ApplicationOrganizationRoleDocumentationSource {\n  readonly label: string;\n  readonly description: string;\n}\n\ninterface ApplicationRoleConfigurationProjectionInput {\n  readonly role?: string;\n  readonly inheritFrom?: string;\n  readonly relatedPrimaryScope: ResourcePrimaryScope;\n}\n\n/**\n * Index companion-exported role specifications by their runtime role token.\n * Engine and application-defined roles intentionally share this namespace.\n */\nexport function indexApplicationRoleDocumentationSources(\n  roleSpecifications: Record<string, unknown> | undefined,\n): ReadonlyMap<string, ApplicationRoleDocumentationSource> {\n  const result = new Map<string, ApplicationRoleDocumentationSource>();\n  for (const candidate of Object.values(roleSpecifications ?? {})) {\n    if (!isPlainObject(candidate) || typeof candidate.ref !== 'string' || candidate.ref.length === 0) continue;\n    if (result.has(candidate.ref)) {\n      throw new Error(`application organization-role projector: duplicate role specification for '${candidate.ref}'`);\n    }\n    result.set(candidate.ref, {\n      ref: candidate.ref,\n      purpose: nonEmptyStringOrNull(candidate.purpose),\n      businessRole: nonEmptyStringOrNull(candidate.businessRole),\n      authorityBoundary: nonEmptyStringOrNull(candidate.authorityBoundary),\n      useWhen: nonEmptyStringOrNull(candidate.useWhen),\n      avoidWhen: nonEmptyStringOrNull(candidate.avoidWhen),\n      businessConstraints: nonEmptyStringArrayOrNull(candidate.businessConstraints),\n    });\n  }\n  return result;\n}\n\n/**\n * Resolve every framework and application-defined organization role from the\n * application's merged runtime registry and authored role specifications.\n * Application-scoped roles are deliberately excluded from this organization\n * administration reference.\n */\nexport function projectApplicationOrganizationRoleDocumentationSources(\n  customRoles: Readonly<Record<string, ApplicationRoleConfigurationProjectionInput>> | undefined,\n  roleSpecsByRef: ReadonlyMap<string, ApplicationRoleDocumentationSource>,\n): readonly ApplicationOrganizationRoleDocumentationSource[] {\n  const configured = new Map<string, ApplicationRoleConfigurationProjectionInput & { readonly role: string }>();\n  for (const config of Object.values(DEFAULT_ORGANIZATION_ROLES)) {\n    if (typeof config.role !== 'string' || config.role.length === 0) {\n      throw new Error('application organization-role projector: framework organization role configuration has no role token');\n    }\n    configured.set(config.role, { ...config, role: config.role });\n  }\n  for (const config of Object.values(customRoles ?? {})) {\n    if (typeof config.role !== 'string' || config.role.length === 0) {\n      throw new Error('application organization-role projector: application organization role configuration has no role token');\n    }\n    if (configured.has(config.role)) {\n      throw new Error(`application organization-role projector: application role '${config.role}' collides with a framework organization role`);\n    }\n    configured.set(config.role, { ...config, role: config.role });\n  }\n\n  return Object.freeze([...configured.values()]\n    .filter((config) => config.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS)\n    .map((config) => {\n      const specification = roleSpecsByRef.get(config.role);\n      if (\n        specification === undefined\n        || specification.purpose === null\n        || specification.authorityBoundary === null\n        || specification.useWhen === null\n        || specification.avoidWhen === null\n        || specification.businessConstraints === null\n      ) {\n        throw new Error(\n          `application organization-role projector: organization role '${config.role}' has no companion-exported role specification with complete consumer guidance`,\n        );\n      }\n      return Object.freeze({\n        role: config.role,\n        inheritFrom: config.inheritFrom ?? null,\n        purpose: specification.purpose,\n        businessRole: specification.businessRole,\n        authorityBoundary: specification.authorityBoundary,\n        useWhen: specification.useWhen,\n        avoidWhen: specification.avoidWhen,\n        businessConstraints: specification.businessConstraints,\n      });\n    })\n    .sort((left, right) => left.role.localeCompare(right.role, 'en-US')));\n}\n\n/**\n * Join role semantics to the exact primary-locale labels shown by the\n * application. Missing values fail closed: publishing a guessed label would\n * make the guide disagree with member-management and role-picker UI.\n */\nexport function resolveApplicationOrganizationRoleDocumentation(\n  roles: readonly ApplicationOrganizationRoleDocumentationSource[],\n  primaryLocaleLabels: Readonly<Record<string, string>>,\n): readonly ApplicationOrganizationRoleDocumentation[] {\n  return Object.freeze(roles.map((role) => Object.freeze({\n    ...role,\n    label: requiredRoleLabel(primaryLocaleLabels, role.role, 'label'),\n    description: requiredRoleLabel(primaryLocaleLabels, role.role, 'description'),\n  })));\n}\n\n/**\n * Materialize the reusable Markdown fact consumed by the Roles and permissions\n * topic. This function knows no application identity: different applications\n * receive different role inputs and therefore different facts.\n */\nexport function createApplicationOrganizationRolesDocumentationFact(\n  roles: readonly ApplicationOrganizationRoleDocumentation[],\n): ApplicationOrganizationRolesDocumentationFact {\n  if (roles.length === 0) throw new Error('technical documentation requires at least one resolved organization role');\n  if (new Set(roles.map((role) => role.role)).size !== roles.length) {\n    throw new Error('technical documentation received duplicate resolved organization roles');\n  }\n\n  const roleByIdentifier = new Map(roles.map((role) => [role.role, role]));\n  const hierarchyDepthByRole = new Map(roles.map((role) => [role.role, hierarchyDepth(role, roleByIdentifier)]));\n  // Readers compare authority from broadest to narrowest. Derive that order\n  // from the actual inheritance chain; sibling branches use visible labels and\n  // stable role tokens only as deterministic tie-breakers.\n  const canonicalRoles = [...roles].sort((left, right) =>\n    hierarchyDepthByRole.get(right.role)! - hierarchyDepthByRole.get(left.role)!\n    || left.label.localeCompare(right.label, 'en-US')\n    || left.role.localeCompare(right.role, 'en-US'));\n\n  const roleSections = canonicalRoles.map((role) => {\n    const inheritedRole = role.inheritFrom === null ? undefined : roleByIdentifier.get(role.inheritFrom);\n    const inheritance = role.inheritFrom === null\n      ? 'This role does not inherit another organization role.'\n      : `This role includes the permissions of **${markdownText(inheritedRole?.label ?? role.inheritFrom)}** (${inlineCode(role.inheritFrom)}).`;\n    const limits = [role.avoidWhen, ...role.businessConstraints]\n      .map((constraint) => `- ${markdownProse(constraint)}`)\n      .join('\\n');\n    return `### ${markdownText(role.label)}\\n\\n${markdownText(role.description)}\\n\\n- **Where it applies:** ${markdownProse(role.authorityBoundary)}\\n- **Inherited access:** ${inheritance}\\n- **Technical identifier:** ${inlineCode(role.role)}\\n\\n#### Can do\\n\\n${markdownProse(role.purpose)}\\n\\n${markdownProse(role.useWhen)}\\n\\n#### Cannot do\\n\\n${limits}\\n\\n#### Can assign\\n\\n${roleAssignmentMarkdown(role, roleByIdentifier)}`;\n  }).join('\\n\\n');\n\n  return Object.freeze({\n    sourceRef: APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_REF,\n    markdown: `These are all the organization roles available in this application. Their names and short descriptions match the application's primary-language interface; the technical identifier is included so you can recognize the same role in an access request, audit record, or API response.\\n\\n${roleSections}\\n\\n> **How inherited access works:** when one role includes another, it receives the included role’s permissions as well as its own. The reverse is not true: assigning the included role never grants the higher role.`,\n    sourceVersion: APPLICATION_ORGANIZATION_ROLES_DOCUMENTATION_SOURCE_VERSION,\n  });\n}\n\nfunction hierarchyDepth(\n  role: ApplicationOrganizationRoleDocumentation,\n  roleByIdentifier: ReadonlyMap<string, ApplicationOrganizationRoleDocumentation>,\n  ancestors = new Set<string>(),\n): number {\n  if (role.inheritFrom === null) return 0;\n  if (ancestors.has(role.role)) {\n    throw new Error(`technical documentation organization-role hierarchy contains a cycle at ${role.role}`);\n  }\n  const inheritedRole = roleByIdentifier.get(role.inheritFrom);\n  if (inheritedRole === undefined) {\n    throw new Error(`technical documentation organization role ${role.role} inherits absent role ${role.inheritFrom}`);\n  }\n  return 1 + hierarchyDepth(inheritedRole, roleByIdentifier, new Set([...ancestors, role.role]));\n}\n\n/**\n * Explain the standard organization-role assignment ceiling from the exact\n * application role graph. This deliberately does not flatten custom roles into\n * a total order: sibling custom branches are outside one another's ceiling.\n * A role must also inherit the administrator gate before it can use the\n * standard membership and unit-assignment controls at all.\n */\nfunction roleAssignmentMarkdown(\n  role: ApplicationOrganizationRoleDocumentation,\n  roleByIdentifier: ReadonlyMap<string, ApplicationOrganizationRoleDocumentation>,\n): string {\n  const effectiveRoles: ApplicationOrganizationRoleDocumentation[] = [];\n  let current: ApplicationOrganizationRoleDocumentation | undefined = role;\n  const visited = new Set<string>();\n  while (current !== undefined) {\n    if (visited.has(current.role)) {\n      throw new Error(`technical documentation organization-role hierarchy contains a cycle at ${current.role}`);\n    }\n    visited.add(current.role);\n    effectiveRoles.push(current);\n    current = current.inheritFrom === null ? undefined : roleByIdentifier.get(current.inheritFrom);\n  }\n\n  if (!effectiveRoles.some((candidate) => candidate.role === CORE_ORG_ROLES.ORG_ADMIN)) {\n    return 'This role cannot use the standard organization-membership or organization-unit assignment controls. It therefore cannot assign an organization or unit role through those controls.';\n  }\n\n  const assignableRoles = effectiveRoles\n    .map((candidate) => `**${markdownText(candidate.label)}** (${inlineCode(candidate.role)})`)\n    .join(', ');\n  return `Through the standard membership and unit-assignment controls, this role can assign: ${assignableRoles}. It cannot assign a role outside this inheritance chain unless the person also holds another organization-wide role whose chain includes it.`;\n}\n\nfunction requiredRoleLabel(\n  labels: Readonly<Record<string, string>>,\n  role: string,\n  field: 'label' | 'description',\n): string {\n  const key = `roles.${role}.${field}`;\n  const value = labels[key];\n  if (typeof value !== 'string' || value.trim().length === 0) {\n    throw new Error(\n      `application organization-role documentation requires primary-locale label '${key}'; generate the application's role labels before publishing documentation`,\n    );\n  }\n  return value.trim();\n}\n\nfunction nonEmptyStringOrNull(value: unknown): string | null {\n  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;\n}\n\nfunction nonEmptyStringArrayOrNull(value: unknown): readonly string[] | null {\n  if (!Array.isArray(value) || value.length === 0) return null;\n  const normalized = value.map(nonEmptyStringOrNull);\n  return normalized.every((entry): entry is string => entry !== null)\n    ? Object.freeze(normalized)\n    : null;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction markdownText(value: string): string {\n  return value.replaceAll(/\\s+/g, ' ').trim().replaceAll('\\\\', '\\\\\\\\').replaceAll(/([`*_[\\]<>#|])/g, '\\\\$1');\n}\n\n/** Role specifications intentionally author small inline-Markdown semantics. */\nfunction markdownProse(value: string): string {\n  return value.replaceAll(/\\s+/g, ' ').trim();\n}\n\nfunction inlineCode(value: string): string {\n  return `\\`${value.replaceAll('`', '&#96;')}\\``;\n}\n"]}

package/dist/esm/companion/application-documentation/application-organization-unit-resource-documentation.d.ts

@@ -0,0 +1,36 @@
+import type { ResourceTag } from '../operation-projection.schemas';
+export declare const APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_REF: "source:companion-projection:organization-unit-aware-resources";
+/** Advances when this projection's shape changes; it is the fact's version wherever provenance cites it. */
+export declare const APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_VERSION = 1;
+/** Exact Markdown fact composed into the organization-unit task pages. */
+export interface ApplicationOrganizationUnitResourcesDocumentationFact {
+    readonly sourceRef: typeof APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_REF;
+    readonly markdown: string;
+    readonly sourceVersion: number;
+}
+/**
+ * Consumer-safe view of one application resource that explicitly opts into
+ * organization-unit narrowing. The internal field holding the unit identity is
+ * deliberately absent: administrators need to know which business information
+ * is narrowed, not how its persistence schema implements that decision.
+ */
+export interface ApplicationOrganizationUnitResourceDocumentation {
+    readonly resourceIdentifier: string;
+    readonly label: string;
+    readonly purpose: string;
+}
+/**
+ * Project the exact startup declaration into a small consumer-safe fact list.
+ *
+ * The declaration is the only authority for inclusion. A unit-shaped URL, a
+ * relationship to organization units, or a similarly named field is not
+ * evidence that runtime authorization narrows the resource. Every included
+ * resource must also have specification-owned purpose prose; publication fails
+ * rather than exposing a raw identifier with no explanation.
+ */
+export declare function projectApplicationOrganizationUnitResourceDocumentation(organizationUnitNarrowing: Readonly<Partial<Record<string, {
+    readonly unitFieldName: string;
+}>>> | undefined, resourceTags: readonly ResourceTag[]): readonly ApplicationOrganizationUnitResourceDocumentation[];
+/** Materialize the application-specific list inserted into unit-access guides. */
+export declare function createApplicationOrganizationUnitResourcesDocumentationFact(resources: readonly ApplicationOrganizationUnitResourceDocumentation[]): ApplicationOrganizationUnitResourcesDocumentationFact;
+//# sourceMappingURL=application-organization-unit-resource-documentation.d.ts.map

package/dist/esm/companion/application-documentation/application-organization-unit-resource-documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-organization-unit-resource-documentation.d.ts","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-organization-unit-resource-documentation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAEnE,eAAO,MAAM,gEAAgE,EAC3E,+DAAwE,CAAC;AAC3E,4GAA4G;AAC5G,eAAO,MAAM,oEAAoE,IAAI,CAAC;AAEtF,0EAA0E;AAC1E,MAAM,WAAW,qDAAqD;IACpE,QAAQ,CAAC,SAAS,EAAE,OAAO,gEAAgE,CAAC;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gDAAgD;IAC/D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,uDAAuD,CACrE,yBAAyB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC,GAAG,SAAS,EAC5G,YAAY,EAAE,SAAS,WAAW,EAAE,GACnC,SAAS,gDAAgD,EAAE,CA4B7D;AAED,kFAAkF;AAClF,wBAAgB,2DAA2D,CACzE,SAAS,EAAE,SAAS,gDAAgD,EAAE,GACrE,qDAAqD,CAiBvD"}

package/dist/esm/companion/application-documentation/application-organization-unit-resource-documentation.js

@@ -0,0 +1,71 @@
+export const APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_REF = 'source:companion-projection:organization-unit-aware-resources';
+/** Advances when this projection's shape changes; it is the fact's version wherever provenance cites it. */
+export const APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_VERSION = 1;
+/**
+ * Project the exact startup declaration into a small consumer-safe fact list.
+ *
+ * The declaration is the only authority for inclusion. A unit-shaped URL, a
+ * relationship to organization units, or a similarly named field is not
+ * evidence that runtime authorization narrows the resource. Every included
+ * resource must also have specification-owned purpose prose; publication fails
+ * rather than exposing a raw identifier with no explanation.
+ */
+export function projectApplicationOrganizationUnitResourceDocumentation(organizationUnitNarrowing, resourceTags) {
+    const tagsByIdentifier = new Map();
+    for (const tag of resourceTags) {
+        if (tagsByIdentifier.has(tag.name)) {
+            throw new Error(`application organization-unit resource projector: duplicate resource tag '${tag.name}'`);
+        }
+        tagsByIdentifier.set(tag.name, tag);
+    }
+    return Object.freeze(Object.entries(organizationUnitNarrowing ?? {})
+        .filter((entry) => entry[1] !== undefined)
+        .map(([resourceIdentifier, declaration]) => {
+        if (declaration.unitFieldName.trim().length === 0) {
+            throw new Error(`application organization-unit resource projector: '${resourceIdentifier}' has an empty narrowing field declaration`);
+        }
+        const tag = tagsByIdentifier.get(resourceIdentifier);
+        if (tag?.description === undefined || tag.description.trim().length === 0) {
+            throw new Error(`application organization-unit resource projector: narrowed resource '${resourceIdentifier}' has no specification-owned purpose`);
+        }
+        return Object.freeze({
+            resourceIdentifier,
+            label: resourceDisplayLabel(resourceIdentifier),
+            purpose: tag.description.trim(),
+        });
+    })
+        .sort((left, right) => left.label.localeCompare(right.label, 'en-US') || left.resourceIdentifier.localeCompare(right.resourceIdentifier, 'en-US')));
+}
+/** Materialize the application-specific list inserted into unit-access guides. */
+export function createApplicationOrganizationUnitResourcesDocumentationFact(resources) {
+    if (new Set(resources.map((resource) => resource.resourceIdentifier)).size !== resources.length) {
+        throw new Error('technical documentation received duplicate organization-unit-aware resources');
+    }
+    const canonicalResources = [...resources]
+        .sort((left, right) => left.label.localeCompare(right.label, 'en-US') || left.resourceIdentifier.localeCompare(right.resourceIdentifier, 'en-US'));
+    const markdown = canonicalResources.length === 0
+        ? '**This application does not currently declare any business resource as organization-unit-aware.** A unit assignment therefore grants no additional access until the application publishes such a resource.'
+        : `This application currently applies organization-unit access to:\n\n${canonicalResources
+            .map((resource) => `- **${markdownText(resource.label)}** — ${markdownText(resource.purpose)}`)
+            .join('\n')}\n\nOnly the resources listed here use unit assignments. Other application information continues to follow its organization-wide operation rules.`;
+    return Object.freeze({
+        sourceRef: APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_REF,
+        markdown,
+        sourceVersion: APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_VERSION,
+    });
+}
+/** Match the native API-reference fallback without changing resource identity. */
+function resourceDisplayLabel(identifier) {
+    return identifier
+        .replaceAll(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replaceAll(/[-_]+/g, ' ')
+        .trim()
+        .split(/\s+/u)
+        .filter(Boolean)
+        .map((word) => (/^[A-Z0-9]+$/u.test(word) ? word : `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`))
+        .join(' ');
+}
+function markdownText(value) {
+    return value.replaceAll(/\s+/g, ' ').trim().replaceAll('\\', '\\\\').replaceAll(/([`*_[\]<>#|])/g, '\\$1');
+}
+//# sourceMappingURL=application-organization-unit-resource-documentation.js.map

package/dist/esm/companion/application-documentation/application-organization-unit-resource-documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-organization-unit-resource-documentation.js","sourceRoot":"","sources":["../../../../../src/companion/application-documentation/application-organization-unit-resource-documentation.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n} from '@wildo-ai/saas-specifications/technical-documentation';\n\nimport type { ResourceTag } from '../operation-projection.schemas';\n\nexport const APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_REF =\n  'source:companion-projection:organization-unit-aware-resources' as const;\n/** Advances when this projection's shape changes; it is the fact's version wherever provenance cites it. */\nexport const APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_VERSION = 1;\n\n/** Exact Markdown fact composed into the organization-unit task pages. */\nexport interface ApplicationOrganizationUnitResourcesDocumentationFact {\n  readonly sourceRef: typeof APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_REF;\n  readonly markdown: string;\n  readonly sourceVersion: number;\n}\n\n/**\n * Consumer-safe view of one application resource that explicitly opts into\n * organization-unit narrowing. The internal field holding the unit identity is\n * deliberately absent: administrators need to know which business information\n * is narrowed, not how its persistence schema implements that decision.\n */\nexport interface ApplicationOrganizationUnitResourceDocumentation {\n  readonly resourceIdentifier: string;\n  readonly label: string;\n  readonly purpose: string;\n}\n\n/**\n * Project the exact startup declaration into a small consumer-safe fact list.\n *\n * The declaration is the only authority for inclusion. A unit-shaped URL, a\n * relationship to organization units, or a similarly named field is not\n * evidence that runtime authorization narrows the resource. Every included\n * resource must also have specification-owned purpose prose; publication fails\n * rather than exposing a raw identifier with no explanation.\n */\nexport function projectApplicationOrganizationUnitResourceDocumentation(\n  organizationUnitNarrowing: Readonly<Partial<Record<string, { readonly unitFieldName: string }>>> | undefined,\n  resourceTags: readonly ResourceTag[],\n): readonly ApplicationOrganizationUnitResourceDocumentation[] {\n  const tagsByIdentifier = new Map<string, ResourceTag>();\n  for (const tag of resourceTags) {\n    if (tagsByIdentifier.has(tag.name)) {\n      throw new Error(`application organization-unit resource projector: duplicate resource tag '${tag.name}'`);\n    }\n    tagsByIdentifier.set(tag.name, tag);\n  }\n\n  return Object.freeze(Object.entries(organizationUnitNarrowing ?? {})\n    .filter((entry): entry is [string, { readonly unitFieldName: string }] => entry[1] !== undefined)\n    .map(([resourceIdentifier, declaration]) => {\n      if (declaration.unitFieldName.trim().length === 0) {\n        throw new Error(`application organization-unit resource projector: '${resourceIdentifier}' has an empty narrowing field declaration`);\n      }\n      const tag = tagsByIdentifier.get(resourceIdentifier);\n      if (tag?.description === undefined || tag.description.trim().length === 0) {\n        throw new Error(\n          `application organization-unit resource projector: narrowed resource '${resourceIdentifier}' has no specification-owned purpose`,\n        );\n      }\n      return Object.freeze({\n        resourceIdentifier,\n        label: resourceDisplayLabel(resourceIdentifier),\n        purpose: tag.description.trim(),\n      });\n    })\n    .sort((left, right) => left.label.localeCompare(right.label, 'en-US') || left.resourceIdentifier.localeCompare(right.resourceIdentifier, 'en-US')));\n}\n\n/** Materialize the application-specific list inserted into unit-access guides. */\nexport function createApplicationOrganizationUnitResourcesDocumentationFact(\n  resources: readonly ApplicationOrganizationUnitResourceDocumentation[],\n): ApplicationOrganizationUnitResourcesDocumentationFact {\n  if (new Set(resources.map((resource) => resource.resourceIdentifier)).size !== resources.length) {\n    throw new Error('technical documentation received duplicate organization-unit-aware resources');\n  }\n  const canonicalResources = [...resources]\n    .sort((left, right) => left.label.localeCompare(right.label, 'en-US') || left.resourceIdentifier.localeCompare(right.resourceIdentifier, 'en-US'));\n  const markdown = canonicalResources.length === 0\n    ? '**This application does not currently declare any business resource as organization-unit-aware.** A unit assignment therefore grants no additional access until the application publishes such a resource.'\n    : `This application currently applies organization-unit access to:\\n\\n${canonicalResources\n      .map((resource) => `- **${markdownText(resource.label)}** — ${markdownText(resource.purpose)}`)\n      .join('\\n')}\\n\\nOnly the resources listed here use unit assignments. Other application information continues to follow its organization-wide operation rules.`;\n\n  return Object.freeze({\n    sourceRef: APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_REF,\n    markdown,\n    sourceVersion: APPLICATION_ORGANIZATION_UNIT_RESOURCES_DOCUMENTATION_SOURCE_VERSION,\n  });\n}\n\n/** Match the native API-reference fallback without changing resource identity. */\nfunction resourceDisplayLabel(identifier: string): string {\n  return identifier\n    .replaceAll(/([a-z0-9])([A-Z])/g, '$1 $2')\n    .replaceAll(/[-_]+/g, ' ')\n    .trim()\n    .split(/\\s+/u)\n    .filter(Boolean)\n    .map((word) => (/^[A-Z0-9]+$/u.test(word) ? word : `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`))\n    .join(' ');\n}\n\nfunction markdownText(value: string): string {\n  return value.replaceAll(/\\s+/g, ' ').trim().replaceAll('\\\\', '\\\\\\\\').replaceAll(/([`*_[\\]<>#|])/g, '\\\\$1');\n}\n"]}

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

@@ -0,0 +1,37 @@
+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';
+import { APPLICATION_CONSUMER_DOCUMENTATION_COMPANION_PROJECTION_SOURCE_PREFIX } from '../../content/application-consumer-documentation-content-manifest.schemas';
+import { type ApplicationOrganizationUnitResourcesDocumentationFact } from './application-organization-unit-resource-documentation';
+export interface EngineContentUnitDefinition {
+    readonly kind: TechnicalDocumentationUnitKind;
+    readonly readerAudiences: readonly TechnicalDocumentationReaderAudience[];
+    readonly accessClass: TechnicalDocumentationAccessClass;
+    readonly applicabilityRequirements: readonly TechnicalDocumentationApplicabilityRequirementV1[];
+    readonly relatedUnitRefs: readonly string[];
+    readonly apiReferenceTargets?: readonly {
+        readonly label: string;
+        readonly target: TechnicalDocumentationApiReferenceTargetV1;
+    }[];
+}
+/** Public, semantic role inventory supplied by the resolved application companion. */
+export interface ApplicationOrganizationRolesDocumentationFact {
+    readonly sourceRef: `${typeof APPLICATION_CONSUMER_DOCUMENTATION_COMPANION_PROJECTION_SOURCE_PREFIX}${string}`;
+    readonly markdown: string;
+    readonly sourceVersion: number;
+}
+/**
+ * The engine-owned editorial topology: each verified authored unit has one
+ * consumer-documentation role and an explicit set of reader destinations.
+ *
+ * This is deliberately separate from Markdown. Markdown owns the narrative
+ * and title; this map owns type, audience, publication posture and navigation
+ * relationships, allowing the projector to reject a mismatched content set.
+ */
+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.
+ */
+export declare function projectEngineApplicationConsumerContentBundle(bundle: LoadedApplicationConsumerDocumentationContentBundleV1, engineSpecificationCatalog: EngineDocumentationSpecificationCatalogV1, unitDefinitions?: Readonly<Record<string, EngineContentUnitDefinition>>, applicationOrganizationRolesFact?: ApplicationOrganizationRolesDocumentationFact, applicationOrganizationUnitResourcesFact?: ApplicationOrganizationUnitResourcesDocumentationFact): TechnicalDocumentationUnitV1[];
+//# sourceMappingURL=technical-documentation-engine-content-bundle.d.ts.map

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

@@ -0,0 +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"}