@intentset/publisher 0.4.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coral Reef Ventures, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/dist/help.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The help file (spec/publication.md §5): every tip of every document
+ * published in a run, keyed by the ID it explains, for a product's runtime to
+ * show beside the control that delivers that behavior. Written beside the
+ * documents whenever the request is accepted, so a runtime can rely on it.
+ *
+ * What gates a tip is what gated its document: a tip is written exactly when
+ * its knowledge was published in the same run. The key is the explained
+ * artifact's ID whatever that artifact's visibility, because a product that
+ * binds a control to the ID has already written it where the same reader can
+ * see it, and nothing else of that artifact is carried: never its title, path,
+ * status or prose. Two documents tipping one ID: the lower knowledge ID wins.
+ */
+import type { Graph, Visibility } from "@intentset/core";
+import type { Snapshot } from "./project.ts";
+import type { PublicationRequest } from "./request.ts";
+export declare const HELP_PROFILE = "intentset/help/0.1";
+/** The file's name beside the published documents. */
+export declare const HELP_FILE = "help.json";
+export interface HelpKnowledge {
+    id: string;
+    title: string;
+    /** `<ID>.md`, the published document. */
+    path: string;
+}
+export interface HelpTip {
+    /** The tip as written on the knowledge record. */
+    text: string;
+    /** The knowledge the tip comes from, one of `knowledge`. */
+    knowledge: string;
+}
+/** `help.json`, in the order it is written. */
+export interface HelpFile {
+    profile: typeof HELP_PROFILE;
+    derived: true;
+    projection: Visibility;
+    snapshot: Snapshot;
+    audience: string;
+    availability: {
+        product: string;
+        release: string;
+        role: string;
+        edition: string;
+        flags: string[];
+    };
+    publishedAt: string;
+    /** One entry per published document, sorted by ID. */
+    knowledge: HelpKnowledge[];
+    /** By explained ID, sorted. */
+    tips: Record<string, HelpTip>;
+}
+export interface HelpOptions {
+    snapshot: Snapshot;
+    publishedAt: string;
+}
+/** The help file for the documents a run published, which are given by knowledge ID. */
+export declare function helpFile(graph: Graph, publishedIds: readonly string[], request: PublicationRequest, options: HelpOptions): HelpFile;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAY,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,YAAY,uBAAuB,CAAC;AACjD,sDAAsD;AACtD,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,OAAO;IACtB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,OAAO,YAAY,CAAC;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACnG,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wFAAwF;AACxF,wBAAgB,QAAQ,CACtB,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,WAAW,GACnB,QAAQ,CAgCV"}

package/dist/help.js

@@ -0,0 +1,41 @@
+import { compareStrings } from "./diagnostic.js";
+export const HELP_PROFILE = "intentset/help/0.1";
+/** The file's name beside the published documents. */
+export const HELP_FILE = "help.json";
+/** The help file for the documents a run published, which are given by knowledge ID. */
+export function helpFile(graph, publishedIds, request, options) {
+    const ids = [...publishedIds].sort(compareStrings);
+    const knowledge = [];
+    const tips = {};
+    const claimed = new Map();
+    for (const id of ids) {
+        const artifact = graph.artifacts.get(id);
+        knowledge.push({ id, title: artifact.meta.title, path: `${id}.md` });
+        for (const key of Object.keys(artifact.meta.tips ?? {}).sort(compareStrings)) {
+            // ids are ascending, so the first claim on a key is the lowest knowledge ID.
+            if (claimed.has(key))
+                continue;
+            claimed.set(key, { text: artifact.meta.tips[key], knowledge: id });
+        }
+    }
+    for (const key of [...claimed.keys()].sort(compareStrings))
+        tips[key] = claimed.get(key);
+    return {
+        profile: HELP_PROFILE,
+        derived: true,
+        projection: request.visibility,
+        snapshot: { commit: options.snapshot.commit, graphHash: options.snapshot.graphHash },
+        audience: request.audience,
+        availability: {
+            product: request.product,
+            release: request.release,
+            role: request.role,
+            edition: request.edition,
+            flags: [...new Set(request.flags)].sort(compareStrings),
+        },
+        publishedAt: options.publishedAt,
+        knowledge,
+        tips,
+    };
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AACjD,sDAAsD;AACtD,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AAoCrC,wFAAwF;AACxF,MAAM,UAAU,QAAQ,CACtB,KAAY,EACZ,YAA+B,EAC/B,OAA2B,EAC3B,OAAoB;IAEpB,MAAM,GAAG,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACnD,MAAM,SAAS,GAAoB,EAAE,CAAC;IACtC,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC3C,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAa,CAAC;QACrD,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QACrE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;YAC7E,6EAA6E;YAC7E,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC/B,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAG,QAAQ,CAAC,IAAI,CAAC,IAA+B,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;QAAE,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAY,CAAC;IACpG,OAAO;QACL,OAAO,EAAE,YAAY;QACrB,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE;QACpF,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,YAAY,EAAE;YACZ,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;SACxD;QACD,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,SAAS;QACT,IAAI;KACL,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -6,6 +6,7 @@
 export { bodyLineOffset } from "./body.ts";
 export { type Chunk, type ChunkOptions, type ChunkSource, toChunks } from "./chunks.ts";
 export { type GenerateOptions, type GeneratedDocument, PUBLICATION_KEY, PUBLICATION_PROFILE, type PublicationMeta, type SourceStamp, checkGenerated, generateDocument, markerLine, marksetSource, publicationMeta, } from "./generate.ts";
+export { HELP_FILE, HELP_PROFILE, type HelpFile, type HelpKnowledge, type HelpOptions, type HelpTip, helpFile, } from "./help.ts";
 export { EXCLUSION_REASONS, type Exclusion, type ExclusionReason, type ProjectOptions, type Projection, type Snapshot, exclusionReason, project, } from "./project.ts";
 export { type PublicationIndex, type PublishOptions, type PublishResult, type PublishedDocument, REFUSAL_REASONS, type RefusalReason, publish, renderDocument, } from "./publish.ts";
 export { type Reference, type ReferenceKind, checkReferences, checkTitles, findReferences, resolveTarget, titlePattern, } from "./references.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,eAAe,EACf,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,eAAe,EACf,KAAK,aAAa,EAClB,OAAO,EACP,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,cAAc,EACnB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,eAAe,EACf,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,eAAe,EACf,KAAK,aAAa,EAClB,OAAO,EACP,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,cAAc,EACnB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@
 export { bodyLineOffset } from "./body.js";
 export { toChunks } from "./chunks.js";
 export { PUBLICATION_KEY, PUBLICATION_PROFILE, checkGenerated, generateDocument, markerLine, marksetSource, publicationMeta, } from "./generate.js";
+export { HELP_FILE, HELP_PROFILE, helpFile, } from "./help.js";
 export { EXCLUSION_REASONS, exclusionReason, project, } from "./project.js";
 export { REFUSAL_REASONS, publish, renderDocument, } from "./publish.js";
 export { checkReferences, checkTitles, findReferences, resolveTarget, titlePattern, } from "./references.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAmD,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAGL,eAAe,EACf,mBAAmB,EAGnB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EAMjB,eAAe,EACf,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAKL,eAAe,EAEf,OAAO,EACP,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,iBAAiB,EAEjB,kBAAkB,EAElB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,EACX,gBAAgB,EAGhB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAkB,QAAQ,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAmD,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAGL,eAAe,EACf,mBAAmB,EAGnB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,SAAS,EACT,YAAY,EAKZ,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EAMjB,eAAe,EACf,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAKL,eAAe,EAEf,OAAO,EACP,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,iBAAiB,EAEjB,kBAAkB,EAElB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,EACX,gBAAgB,EAGhB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAkB,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/publish.d.ts

@@ -1,5 +1,6 @@
 import { type Diagnostic, type Graph, type Registries } from "@intentset/core";
 import { type GeneratedDocument, type PublicationMeta } from "./generate.ts";
+import { type HelpFile } from "./help.ts";
 import { type Snapshot } from "./project.ts";
 import { type IndexedRequest, type PublicationRequest } from "./request.ts";
 import type { ReviewStatus } from "./review.ts";
@@ -28,6 +29,8 @@ export interface PublicationIndex {
 export interface PublishResult {
     documents: PublishedDocument[];
     index: PublicationIndex;
+    /** The help file (spec/publication.md §5), or null when the request was refused. */
+    help: HelpFile | null;
     diagnostics: Diagnostic[];
     ok: boolean;
 }

package/dist/publish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAoB,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAwB,KAAK,QAAQ,EAAW,MAAM,cAAc,CAAC;AAE5E,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAA0B,MAAM,cAAc,CAAC;AACpG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,yEAAyE;AACzE,eAAO,MAAM,eAAe,YAAI,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,CAAU,CAAC;AACvF,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,kGAAkG;IAClG,WAAW,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,4EAA4E;IAC5E,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,wBAAgB,OAAO,CACrB,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,aAAa,CAsEf;AAUD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAOpF"}
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"AA0BA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAoB,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,KAAK,QAAQ,EAAY,MAAM,WAAW,CAAC;AACpD,OAAO,EAAwB,KAAK,QAAQ,EAAW,MAAM,cAAc,CAAC;AAE5E,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAA0B,MAAM,cAAc,CAAC;AACpG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,yEAAyE;AACzE,eAAO,MAAM,eAAe,YAAI,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,CAAU,CAAC;AACvF,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,kGAAkG;IAClG,WAAW,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,4EAA4E;IAC5E,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,KAAK,EAAE,gBAAgB,CAAC;IACxB,oFAAoF;IACpF,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,wBAAgB,OAAO,CACrB,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,aAAa,CA+Ef;AAUD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAOpF"}

package/dist/publish.js

@@ -12,6 +12,9 @@
  * what is actually being published, so a document that links to one refused
  * here is refused in turn; this repeats until nothing more is refused.
  *
+ * The help file (help.ts) carries every published document's tips, keyed by
+ * the ID each explains, for a product's runtime.
+ *
  * The index is what a customer-facing tool may read (Core §10): the snapshot,
  * the request without its authorization flags, the published IDs, and the
  * number of artifacts excluded for each reason. It names nothing that was not
@@ -26,6 +29,7 @@ import { parseDocument } from "@markset-lang/parser";
 import { defaultStylesheetPath, renderPage } from "@markset-lang/render-html";
 import { compareStrings } from "./diagnostic.js";
 import { generateDocument } from "./generate.js";
+import { helpFile } from "./help.js";
 import { project } from "./project.js";
 import { checkReferences, checkTitles } from "./references.js";
 import { admits, indexedRequest } from "./request.js";
@@ -95,6 +99,9 @@ export function publish(graph, registries, request, options) {
     const sorted = sortDiagnostics(diagnostics);
     return {
         documents,
+        help: req === null
+            ? null
+            : helpFile(graph, documents.map((document) => document.id), req, options),
         index: {
             snapshot: { commit: options.snapshot.commit, graphHash: options.snapshot.graphHash },
             request: req === null ? null : indexedRequest(req),

package/dist/publish.js.map

@@ -1 +1 @@
-{"version":3,"file":"publish.js","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"publish.js","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentset/publisher",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Audience and release projection of reviewed knowledge into Markset documents with provenance.",
   "license": "MIT",
   "type": "module",
@@ -28,9 +28,9 @@
     }
   },
   "dependencies": {
-    "@intentset/core": "^0.4.0",
-    "@intentset/markset-adapter": "^0.4.0",
+    "@intentset/core": "^0.5.0",
+    "@intentset/markset-adapter": "^0.5.0",
     "@markset-lang/parser": "0.3.4",
     "@markset-lang/render-html": "0.3.4"
   }
-}
+}

package/src/help.ts

@@ -0,0 +1,95 @@
+/**
+ * The help file (spec/publication.md §5): every tip of every document
+ * published in a run, keyed by the ID it explains, for a product's runtime to
+ * show beside the control that delivers that behavior. Written beside the
+ * documents whenever the request is accepted, so a runtime can rely on it.
+ *
+ * What gates a tip is what gated its document: a tip is written exactly when
+ * its knowledge was published in the same run. The key is the explained
+ * artifact's ID whatever that artifact's visibility, because a product that
+ * binds a control to the ID has already written it where the same reader can
+ * see it, and nothing else of that artifact is carried: never its title, path,
+ * status or prose. Two documents tipping one ID: the lower knowledge ID wins.
+ */
+import type { Artifact, Graph, Visibility } from "@intentset/core";
+import { compareStrings } from "./diagnostic.ts";
+import type { Snapshot } from "./project.ts";
+import type { PublicationRequest } from "./request.ts";
+
+export const HELP_PROFILE = "intentset/help/0.1";
+/** The file's name beside the published documents. */
+export const HELP_FILE = "help.json";
+
+export interface HelpKnowledge {
+  id: string;
+  title: string;
+  /** `<ID>.md`, the published document. */
+  path: string;
+}
+
+export interface HelpTip {
+  /** The tip as written on the knowledge record. */
+  text: string;
+  /** The knowledge the tip comes from, one of `knowledge`. */
+  knowledge: string;
+}
+
+/** `help.json`, in the order it is written. */
+export interface HelpFile {
+  profile: typeof HELP_PROFILE;
+  derived: true;
+  projection: Visibility;
+  snapshot: Snapshot;
+  audience: string;
+  availability: { product: string; release: string; role: string; edition: string; flags: string[] };
+  publishedAt: string;
+  /** One entry per published document, sorted by ID. */
+  knowledge: HelpKnowledge[];
+  /** By explained ID, sorted. */
+  tips: Record<string, HelpTip>;
+}
+
+export interface HelpOptions {
+  snapshot: Snapshot;
+  publishedAt: string;
+}
+
+/** The help file for the documents a run published, which are given by knowledge ID. */
+export function helpFile(
+  graph: Graph,
+  publishedIds: readonly string[],
+  request: PublicationRequest,
+  options: HelpOptions,
+): HelpFile {
+  const ids = [...publishedIds].sort(compareStrings);
+  const knowledge: HelpKnowledge[] = [];
+  const tips: Record<string, HelpTip> = {};
+  const claimed = new Map<string, HelpTip>();
+  for (const id of ids) {
+    const artifact = graph.artifacts.get(id) as Artifact;
+    knowledge.push({ id, title: artifact.meta.title, path: `${id}.md` });
+    for (const key of Object.keys(artifact.meta.tips ?? {}).sort(compareStrings)) {
+      // ids are ascending, so the first claim on a key is the lowest knowledge ID.
+      if (claimed.has(key)) continue;
+      claimed.set(key, { text: (artifact.meta.tips as Record<string, string>)[key], knowledge: id });
+    }
+  }
+  for (const key of [...claimed.keys()].sort(compareStrings)) tips[key] = claimed.get(key) as HelpTip;
+  return {
+    profile: HELP_PROFILE,
+    derived: true,
+    projection: request.visibility,
+    snapshot: { commit: options.snapshot.commit, graphHash: options.snapshot.graphHash },
+    audience: request.audience,
+    availability: {
+      product: request.product,
+      release: request.release,
+      role: request.role,
+      edition: request.edition,
+      flags: [...new Set(request.flags)].sort(compareStrings),
+    },
+    publishedAt: options.publishedAt,
+    knowledge,
+    tips,
+  };
+}

package/src/index.ts

@@ -18,6 +18,15 @@ export {
   marksetSource,
   publicationMeta,
 } from "./generate.ts";
+export {
+  HELP_FILE,
+  HELP_PROFILE,
+  type HelpFile,
+  type HelpKnowledge,
+  type HelpOptions,
+  type HelpTip,
+  helpFile,
+} from "./help.ts";
 export {
   EXCLUSION_REASONS,
   type Exclusion,

package/src/publish.ts

@@ -12,6 +12,9 @@
  * what is actually being published, so a document that links to one refused
  * here is refused in turn; this repeats until nothing more is refused.
  *
+ * The help file (help.ts) carries every published document's tips, keyed by
+ * the ID each explains, for a product's runtime.
+ *
  * The index is what a customer-facing tool may read (Core §10): the snapshot,
  * the request without its authorization flags, the published IDs, and the
  * number of artifacts excluded for each reason. It names nothing that was not
@@ -34,6 +37,7 @@ import { parseDocument } from "@markset-lang/parser";
 import { defaultStylesheetPath, renderPage } from "@markset-lang/render-html";
 import { compareStrings } from "./diagnostic.ts";
 import { type GeneratedDocument, type PublicationMeta, generateDocument } from "./generate.ts";
+import { type HelpFile, helpFile } from "./help.ts";
 import { type ExclusionReason, type Snapshot, project } from "./project.ts";
 import { checkReferences, checkTitles } from "./references.ts";
 import { type IndexedRequest, type PublicationRequest, admits, indexedRequest } from "./request.ts";
@@ -68,6 +72,8 @@ export interface PublicationIndex {
 export interface PublishResult {
   documents: PublishedDocument[];
   index: PublicationIndex;
+  /** The help file (spec/publication.md §5), or null when the request was refused. */
+  help: HelpFile | null;
   diagnostics: Diagnostic[];
   ok: boolean;
 }
@@ -138,6 +144,15 @@ export function publish(
   const sorted = sortDiagnostics(diagnostics);
   return {
     documents,
+    help:
+      req === null
+        ? null
+        : helpFile(
+            graph,
+            documents.map((document) => document.id),
+            req,
+            options,
+          ),
     index: {
       snapshot: { commit: options.snapshot.commit, graphHash: options.snapshot.graphHash },
       request: req === null ? null : indexedRequest(req),