yarramate 1.31.0 → 1.32.0

package/dist/adapters/likec4-export.d.ts

@@ -1,4 +1,5 @@
 import { type AdapterMapping } from '../adapter-mapping.js';
+import { type Branding } from '../branding.js';
 import type { StateComparison } from '../architecture-state.js';
 import type { ProjectionResult } from '../projection.js';
 import type { LikeC4KindMapping } from './likec4-kind-mapping.js';
@@ -21,6 +22,8 @@ export type LikeC4ExportResult = {
 };
 export interface LikeC4ExportOptions {
     readonly comparison?: StateComparison;
+    /** The banner names the host's product (#546, ADR 0158); absent, the engine. */
+    readonly branding?: Branding;
     /** Git-derived review overlay (ADR 0066): subjects new or changed in a
      *  ref range carry metadata and view styling; nothing is authored. */
     readonly gitChange?: GitChangeOverlay;

package/dist/adapters/likec4-export.js

@@ -1,4 +1,5 @@
 import { adapterMappingEntryLocation, adapterMappingLocation, } from '../adapter-mapping.js';
+import { resolveBranding } from '../branding.js';
 import { diagnosticOrder } from '../source-document.js';
 const identifier = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 const valueFor = (claims, subject, predicate) => {
@@ -114,8 +115,10 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
             diagnostics: diagnostics.sort(diagnosticOrder),
         };
     }
+    const brand = resolveBranding(options.branding);
     const lines = [
-        '// Generated by YarraMate. Edit the native documents, not this file.',
+        `// Generated by ${brand.productName}. Edit the native documents, not this file.`,
+        ...(brand.vendorLine === null ? [] : [`// ${brand.vendorLine}`]),
         'model {',
     ];
     for (const concept of concepts) {

package/dist/adapters/likec4-project-export.d.ts

@@ -1,4 +1,5 @@
 import type { WorkspaceSource } from '../compiler.js';
+import { type Branding } from '../branding.js';
 import { type LikeC4PreparationDiagnostic } from './likec4-prepare.js';
 import type { GitChangeOverlay } from './likec4-export.js';
 import { type LikeC4ProjectDefinition, type PreparedLikeC4ProjectView } from './likec4-project.js';
@@ -26,6 +27,12 @@ export interface LikeC4ProjectExportInput {
     readonly requireMappedRelationships: boolean;
     /** The git-derived review overlay, when the CLI derived one. */
     readonly gitChange?: GitChangeOverlay;
+    /**
+     * The host's branding (#546, ADR 0158): the model banner and the project
+     * name in `likec4.config.json`. The marker file and its digests are
+     * machinery and keep their names.
+     */
+    readonly branding?: Branding;
 }
 export interface LikeC4ProjectExported {
     readonly ok: true;
@@ -38,6 +45,8 @@ export interface LikeC4ProjectExported {
     readonly kindMappingIdentity?: string;
     /** Every source that fed the export, for the marker's input digests. */
     readonly inputs: readonly WorkspaceSource[];
+    /** Echoed from the input so `generatedProjectFiles` names the project for it. */
+    readonly branding?: Branding;
 }
 export type LikeC4ProjectExportResult = LikeC4ProjectExported | {
     readonly ok: false;
@@ -62,7 +71,7 @@ export interface GeneratedProjectOwnership {
 }
 export declare const ownershipOf: (exported: LikeC4ProjectExported) => GeneratedProjectOwnership;
 export declare const inputDigestsOf: (inputs: readonly WorkspaceSource[]) => Readonly<Record<string, string>>;
-export declare const projectNameOf: (projectIdentity: string) => string;
+export declare const projectNameOf: (projectIdentity: string, branding?: Branding) => string;
 /**
  * The four files a generated project holds, exactly as the CLI writes them
  * under its output directory: the config, the model, the specification the

package/dist/adapters/likec4-project-export.js

@@ -1,4 +1,5 @@
 import { parseDocument } from 'yaml';
+import { brandSlug, resolveBranding } from '../branding.js';
 import { sha256Hex } from '../digest.js';
 import { LIKEC4_SPECIFICATION_SOURCE } from '../likec4-specification.generated.js';
 import { locateSourcePath } from '../source-document.js';
@@ -165,7 +166,10 @@ export const exportLikeC4ProjectFromSources = (input) => {
         }
         renderedViewIds.add(renderedId);
     }
-    const exported = exportLikeC4Project(definition, successfulViews, input.gitChange === undefined ? {} : { gitChange: input.gitChange });
+    const exported = exportLikeC4Project(definition, successfulViews, {
+        ...(input.gitChange === undefined ? {} : { gitChange: input.gitChange }),
+        ...(input.branding === undefined ? {} : { branding: input.branding }),
+    });
     if (!exported.ok)
         return { ok: false, diagnostics: exported.diagnostics };
     const first = successfulViews[0];
@@ -182,6 +186,7 @@ export const exportLikeC4ProjectFromSources = (input) => {
                 kindMappingIdentity: `${first.prepared.kindMapping.id}@${first.prepared.kindMapping.version}`,
             }),
         inputs: [projectSource, ...sources, ...referencedSources.values()],
+        ...(input.branding === undefined ? {} : { branding: input.branding }),
     };
 };
 // ---------------------------------------------------------------------------
@@ -208,7 +213,7 @@ export const ownershipOf = (exported) => ({
 export const inputDigestsOf = (inputs) => Object.fromEntries(inputs
     .map(({ path, source }) => [path, sha256Hex(source)])
     .sort(([left], [right]) => left.localeCompare(right)));
-export const projectNameOf = (projectIdentity) => `yarramate-${projectIdentity}`.replaceAll(/[^A-Za-z0-9_-]/g, '-');
+export const projectNameOf = (projectIdentity, branding) => `${brandSlug(resolveBranding(branding))}-${projectIdentity}`.replaceAll(/[^A-Za-z0-9_-]/g, '-');
 /**
  * The four files a generated project holds, exactly as the CLI writes them
  * under its output directory: the config, the model, the specification the
@@ -218,7 +223,7 @@ export const projectNameOf = (projectIdentity) => `yarramate-${projectIdentity}`
 export const generatedProjectFiles = (exported) => {
     const configSource = `${JSON.stringify({
         $schema: 'https://likec4.dev/schemas/config.json',
-        name: projectNameOf(exported.projectIdentity),
+        name: projectNameOf(exported.projectIdentity, exported.branding),
         title: exported.project.title,
     }, null, 2)}\n`;
     const markerSource = `${JSON.stringify({

package/dist/adapters/likec4-project.d.ts

@@ -1,3 +1,4 @@
+import type { Branding } from '../branding.js';
 import type { WorkspaceSource } from '../compiler.js';
 import type { LikeC4PreparationResult } from './likec4-prepare.js';
 import { type GitChangeOverlay, type LikeC4ExportResult } from './likec4-export.js';
@@ -59,5 +60,7 @@ export interface PreparedLikeC4ProjectView {
 }
 export interface LikeC4ProjectExportOptions {
     readonly gitChange?: GitChangeOverlay;
+    /** Names the product in the model banner (#546, ADR 0158). */
+    readonly branding?: Branding;
 }
 export declare function exportLikeC4Project(project: LikeC4ProjectDefinition, views: readonly PreparedLikeC4ProjectView[], options?: LikeC4ProjectExportOptions): LikeC4ExportResult;

package/dist/adapters/likec4-project.js

@@ -236,9 +236,10 @@ export function exportLikeC4Project(project, views, options = {}) {
     if (first === undefined) {
         throw new Error('LikeC4 project requires at least one view');
     }
-    const model = exportLikeC4(unionProjection(project, views), first.prepared.subjectMapping, first.prepared.kindMapping, options.gitChange === undefined
-        ? {}
-        : { gitChange: options.gitChange });
+    const model = exportLikeC4(unionProjection(project, views), first.prepared.subjectMapping, first.prepared.kindMapping, {
+        ...(options.gitChange === undefined ? {} : { gitChange: options.gitChange }),
+        ...(options.branding === undefined ? {} : { branding: options.branding }),
+    });
     if (!model.ok)
         return model;
     const startToken = '\nviews {\n';

package/dist/adapters/mcp-cli.js

@@ -7,7 +7,7 @@ import { isMainModule, packageVersion, versionResult, } from '../cli-support.js'
 import { runCli } from '../cli.js';
 import { createFileSystemStore } from '../source-store.js';
 import { loadWorkspaceManifest } from '../workspace.js';
-import { LOOP, STDIO_PROPERTIES, TOOL_CATALOGUE, runTool, } from '../tools/table.js';
+import { STDIO_PROPERTIES, TOOL_CATALOGUE, instructionsFor, runTool, } from '../tools/table.js';
 /** The sentence the stdio rows add, because only here is there a `workspace` to name. */
 const WORKSPACE_SENTENCE = 'Every tool takes the same optional `workspace`; omit it to use the workspace this server was started with, or .yarramate/workspace.yaml under its working directory.';
 const CONVENTIONAL_WORKSPACE = join('.yarramate', 'workspace.yaml');
@@ -236,7 +236,7 @@ export const handleRequest = (request, context = { cwd: process.cwd(), workspace
             protocolVersion: '2025-06-18',
             capabilities: { tools: {} },
             serverInfo: { name: 'yarramate', version: packageVersion },
-            instructions: `The architecture record of a YarraMate workspace. The native documents in the repository are canonical; every read renders them, and yarramate_apply is the one write, the same atomic batch the CLI lands. ${LOOP} ${WORKSPACE_SENTENCE}`,
+            instructions: `${instructionsFor()} ${WORKSPACE_SENTENCE}`,
         });
         return;
     }

package/dist/branding.d.ts

@@ -0,0 +1,86 @@
+/**
+ * White-labelling (#546, ADR 0158): one value, set once by a host, that
+ * names the product on every surface a consumer's users see - the editor
+ * shell, the tool list an agent reads, the workbook's cover sheet and the
+ * LikeC4 banner. Nothing else changes: record formats, diagnostic codes and
+ * the wire protocol are contracts, not branding, and stay `yarramate/...`
+ * and `YM...`. Absent, every surface reads exactly as it always has.
+ *
+ * Pure: no imports, so it sits under every entry (`yarramate/tools`,
+ * `yarramate/workbook`, `yarramate/visual-app`) without weight.
+ */
+export type BrandingLogo = 
+/** Inline markup the host wrote; rendered as the host's own SVG. */
+{
+    readonly svg: string;
+}
+/** An address the page fetches; rendered as an image. */
+ | {
+    readonly url: string;
+};
+export interface Branding {
+    /** "ApertureX", "Halcyon Architecture". Required: a brand without a name is not one. */
+    readonly productName: string;
+    /**
+     * For tight chrome: beside the logo in the brand mark, and in the
+     * authority line ("Checked Halcyon model"). Defaults to `productName`.
+     * `null` draws the logo alone, for a wordmark that already says the name.
+     */
+    readonly shortName?: string | null;
+    /** Beside the title in the editor shell. Nothing is drawn without one. */
+    readonly logo?: BrandingLogo;
+    /**
+     * One CSS colour for the chrome - the authority mark, the notices, the
+     * changeset controls - never the notation: what a node or an edge looks
+     * like is the style preset's, and a comparison's added/removed marks keep
+     * their own tokens.
+     */
+    readonly accent?: string;
+    /** Where the brand mark links. Without it the mark is text, not a link. */
+    readonly docsUrl?: string;
+    /**
+     * The line under the product name, on the editor strip, the workbook's
+     * cover sheet and the LikeC4 banner. Unset: "Powered by yarramate". A
+     * string replaces it; `null` removes it, and with it every other mention
+     * of the engine those surfaces make.
+     */
+    readonly vendorLine?: string | null;
+    /**
+     * The prefix of the tool names an agent reads: `acme` publishes
+     * `acme_design`, `acme_apply`, ... Default `yarramate`. An instruction
+     * written for `yarramate_design` will not find `acme_design`, so a host
+     * that re-prefixes owns its own agent instructions.
+     */
+    readonly toolPrefix?: string;
+}
+/** `Branding` with every default applied, which is what the surfaces read. */
+export interface ResolvedBranding {
+    readonly productName: string;
+    /** `null` when the mark is the logo alone; the authority line then says `productName`. */
+    readonly shortName: string | null;
+    readonly logo?: BrandingLogo;
+    readonly accent?: string;
+    readonly docsUrl?: string;
+    /** `null` when there is none to show. */
+    readonly vendorLine: string | null;
+    readonly toolPrefix: string;
+    /** False is the unbranded product: every surface as it was before #546. */
+    readonly branded: boolean;
+}
+export declare const YARRAMATE_PRODUCT_NAME = "YarraMate";
+export declare const YARRAMATE_TOOL_PREFIX = "yarramate";
+export declare const DEFAULT_VENDOR_LINE = "Powered by yarramate";
+/**
+ * Applies the defaults. `undefined` is the unbranded product. A value with
+ * a blank `productName` or a `toolPrefix` no MCP client could publish is a
+ * host's configuration error and throws, at mount or serve time, rather
+ * than reaching a person as a blank name or an agent as a broken tool list.
+ */
+export declare const resolveBranding: (branding?: Branding) => ResolvedBranding;
+/**
+ * The product name as an identifier segment: the LikeC4 project name is
+ * `<slug>-<project id>`, `yarramate-…` unbranded. Lower-case letters,
+ * digits and single hyphens; a name with nothing usable in it falls back
+ * to the engine's own slug rather than producing an empty segment.
+ */
+export declare const brandSlug: (branding: ResolvedBranding) => string;

package/dist/branding.js

@@ -0,0 +1,80 @@
+/**
+ * White-labelling (#546, ADR 0158): one value, set once by a host, that
+ * names the product on every surface a consumer's users see - the editor
+ * shell, the tool list an agent reads, the workbook's cover sheet and the
+ * LikeC4 banner. Nothing else changes: record formats, diagnostic codes and
+ * the wire protocol are contracts, not branding, and stay `yarramate/...`
+ * and `YM...`. Absent, every surface reads exactly as it always has.
+ *
+ * Pure: no imports, so it sits under every entry (`yarramate/tools`,
+ * `yarramate/workbook`, `yarramate/visual-app`) without weight.
+ */
+export const YARRAMATE_PRODUCT_NAME = 'YarraMate';
+export const YARRAMATE_TOOL_PREFIX = 'yarramate';
+export const DEFAULT_VENDOR_LINE = 'Powered by yarramate';
+/** What an MCP client accepts in a tool name, applied to the prefix alone. */
+const TOOL_PREFIX = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+const UNBRANDED = {
+    productName: YARRAMATE_PRODUCT_NAME,
+    shortName: YARRAMATE_PRODUCT_NAME,
+    vendorLine: null,
+    toolPrefix: YARRAMATE_TOOL_PREFIX,
+    branded: false,
+};
+/**
+ * Applies the defaults. `undefined` is the unbranded product. A value with
+ * a blank `productName` or a `toolPrefix` no MCP client could publish is a
+ * host's configuration error and throws, at mount or serve time, rather
+ * than reaching a person as a blank name or an agent as a broken tool list.
+ */
+export const resolveBranding = (branding) => {
+    if (branding === undefined)
+        return UNBRANDED;
+    const productName = branding.productName.trim();
+    if (productName === '') {
+        throw new TypeError('branding.productName must not be blank');
+    }
+    const toolPrefix = branding.toolPrefix ?? YARRAMATE_TOOL_PREFIX;
+    if (!TOOL_PREFIX.test(toolPrefix)) {
+        throw new TypeError(`branding.toolPrefix "${toolPrefix}" must be letters, digits and hyphens, starting with a letter or digit`);
+    }
+    const shortName = branding.shortName === null ? null : branding.shortName?.trim();
+    const vendorLine = branding.vendorLine === undefined
+        ? DEFAULT_VENDOR_LINE
+        : branding.vendorLine === null || branding.vendorLine.trim() === ''
+            ? null
+            : branding.vendorLine.trim();
+    return {
+        productName,
+        shortName: shortName === null
+            ? null
+            : shortName === undefined || shortName === ''
+                ? productName
+                : shortName,
+        ...(branding.logo === undefined ? {} : { logo: branding.logo }),
+        ...(branding.accent === undefined ? {} : { accent: branding.accent }),
+        ...(branding.docsUrl === undefined ? {} : { docsUrl: branding.docsUrl }),
+        vendorLine,
+        toolPrefix,
+        branded: true,
+    };
+};
+/**
+ * The product name as an identifier segment: the LikeC4 project name is
+ * `<slug>-<project id>`, `yarramate-…` unbranded. Lower-case letters,
+ * digits and single hyphens; a name with nothing usable in it falls back
+ * to the engine's own slug rather than producing an empty segment.
+ */
+export const brandSlug = (branding) => {
+    if (!branding.branded)
+        return YARRAMATE_TOOL_PREFIX;
+    // Split on the runs and join what is left: linear, where a trim by
+    // `^-+|-+$` is polynomial on a name that is mostly hyphens (CodeQL
+    // js/polynomial-redos, the rule that bit #547's walker too).
+    const slug = (branding.shortName ?? branding.productName)
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((part) => part !== '')
+        .join('-');
+    return slug === '' ? YARRAMATE_TOOL_PREFIX : slug;
+};

package/dist/tools/export.js

@@ -157,6 +157,7 @@ export const exportLikeC4 = (workspace, project) => guarded(() => {
             return held === undefined ? undefined : { path, source: held.source };
         },
         requireMappedRelationships: false,
+        ...(workspace.branding === undefined ? {} : { branding: workspace.branding }),
     });
     if (!exported.ok)
         return failed(exported.diagnostics);
@@ -185,7 +186,7 @@ export const exportWorkbook = (workspace, projection) => guarded(() => {
             ...compiled.profileContext.relationshipKindLineages.keys(),
         ].sort(),
         statuses: ['planned', 'current', 'retired'],
-    });
+    }, workspace.branding);
     const stem = evaluated.result.projection.split('@')[0] ?? 'workbook';
     return {
         ok: true,

package/dist/tools/table.d.ts

@@ -1,5 +1,6 @@
 import type { WorkspaceSource } from '../compiler.js';
 import type { ToolWorkspace } from './workspace.js';
+import { type Branding } from '../branding.js';
 /**
  * The tool surface, once (ADR 0156). The stdio adapter and a hosted server
  * publish these rows; `runTool` answers a call over a store, and both
@@ -7,7 +8,18 @@ import type { ToolWorkspace } from './workspace.js';
  * the network read the same names, the same schemas, the same sentences,
  * and get the same text back.
  */
-export type ToolName = 'yarramate_ask' | 'yarramate_design' | 'yarramate_apply' | 'yarramate_check' | 'yarramate_reconcile' | 'yarramate_export';
+export declare const TOOL_VERBS: readonly ['ask', 'design', 'apply', 'check', 'reconcile', 'export'];
+export type ToolVerb = (typeof TOOL_VERBS)[number];
+/**
+ * A published name: the prefix a host chose, an underscore, the verb. The
+ * prefix is branding (#546, ADR 0158); the verb is the contract, and
+ * `runTool` dispatches on it alone.
+ */
+export type ToolNameFor<P extends string> = `${P}_${ToolVerb}`;
+export type ToolName = ToolNameFor<typeof YARRAMATE_PREFIX>;
+declare const YARRAMATE_PREFIX = "yarramate";
+/** The verb behind a name of any prefix; `undefined` for a name that is not a tool's. */
+export declare const toolVerbOf: (name: string) => ToolVerb | undefined;
 /**
  * One row per tool. Generic over the name so a host that adds tools of its
  * own builds `[...TOOL_CATALOGUE, own]` as `ToolDefinition<string>[]` with
@@ -33,7 +45,13 @@ export interface ToolDefinition<N extends string = ToolName> {
  * for the first time has never seen the skill file; the tool list is the
  * only place it learns that design asks, apply lands, and design asks again.
  */
-export declare const LOOP = "The loop: call yarramate_design for the top open question, answer it with the person, land the answer with yarramate_apply, then call yarramate_design again.";
+export declare const loopFor: (branding?: Branding) => string;
+export declare const LOOP: string;
+/**
+ * The `initialize` instructions a server publishes, without the stdio
+ * adapter's sentence about `workspace`: the record, the one write, the loop.
+ */
+export declare const instructionsFor: (branding?: Branding) => string;
 /**
  * The two argument properties that exist only where a filesystem does:
  * `workspace` (which manifest) and `out` (where export writes). The stdio
@@ -42,6 +60,12 @@ export declare const LOOP = "The loop: call yarramate_design for the top open qu
  * words.
  */
 export declare const STDIO_PROPERTIES: Readonly<Record<'workspace' | 'out', Record<string, unknown>>>;
+/**
+ * The rows for a host's branding: the prefix in every name, in the loop
+ * sentence and wherever a description names a sibling tool. Unbranded, or
+ * branded without a `toolPrefix`, this is `TOOL_CATALOGUE` row for row.
+ */
+export declare const toolCatalogueFor: (branding?: Branding) => readonly ToolDefinition<string>[];
 export declare const TOOL_CATALOGUE: readonly ToolDefinition<ToolName>[];
 export interface ToolFile {
     /** Relative, `/`-separated, as the CLI would write it under `out`. */
@@ -78,8 +102,13 @@ export type ToolOutcome = {
  * the function the row names, renders exactly the text the stdio adapter
  * returns for the same call. `yarramate_reconcile` answers `ok: false`
  * with the row's `unavailable` line.
+ *
+ * `name` may carry any prefix (#546): the verb after the last underscore is
+ * what dispatches, and a refusal names the tool by the name it was called
+ * by, so an agent reading `acme_export` in its tool list reads `acme_export`
+ * in the refusal. A name with no tool verb is refused, never thrown.
  */
-export declare const runTool: (name: ToolName, input: Record<string, unknown>, workspace: ToolWorkspace) => ToolOutcome;
+export declare const runTool: (name: string, input: Record<string, unknown>, workspace: ToolWorkspace) => ToolOutcome;
 /** The files a text kind would write under `out`, for a caller with a filesystem. */
 export declare const filesOf: (outcome: ToolOutcome) => readonly ToolFile[];
 export type { WorkspaceSource };