@warpgogol/werkstatt-shared 0.15.0 → 0.16.0

package/src/observability/pipeline-log.ts

@@ -0,0 +1,81 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Provides lightweight structured pipeline log events for build-time content helpers.</purpose>
+<non-goals>
+  <item>Do not persist logs outside the current Node.js process.</item>
+  <item>Do not silence actionable warnings or errors.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0254: add structured expected-fallback log transport for build/check paths.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type PipelineLogSeverity = "debug" | "info" | "notice" | "warning" | "error";
+
+export type PipelineLogKind =
+  "progress" | "expected-fallback" | "advisory" | "external-tool" | "diagnostic" | "error";
+
+export interface PipelineLogEvent {
+  severity: PipelineLogSeverity;
+  kind: PipelineLogKind;
+  message: string;
+  command?: string;
+  pipeline?: string;
+  app?: string;
+  packageName?: string;
+  module?: string;
+  file?: string;
+  line?: number;
+  ruleId?: string;
+  dedupeKey?: string;
+  count?: number;
+  data?: Record<string, unknown>;
+}
+
+interface PipelineLogState {
+  events: PipelineLogEvent[];
+  counts: Map<string, number>;
+}
+
+const STATE_KEY = "__gogolPipelineLogState";
+
+function getState(): PipelineLogState {
+  const root = globalThis as typeof globalThis & { __gogolPipelineLogState?: PipelineLogState };
+  if (!root[STATE_KEY]) {
+    root[STATE_KEY] = { events: [], counts: new Map() };
+  }
+  return root[STATE_KEY];
+}
+
+function renderEvent(event: PipelineLogEvent, count: number): string {
+  const prefix = event.kind === "expected-fallback" ? "fallback" : event.kind;
+  const suffix = count > 1 ? ` (${count} occurrence(s))` : "";
+  return `[${event.severity}:${prefix}] ${event.message}${suffix}`;
+}
+
+export function emitPipelineLogEvent(event: PipelineLogEvent): void {
+  const state = getState();
+  const key = event.dedupeKey ?? `${event.kind}:${event.severity}:${event.message}`;
+  const count = (state.counts.get(key) ?? 0) + 1;
+  state.counts.set(key, count);
+  state.events.push({ ...event, count });
+
+  if (event.severity === "debug") return;
+  if (event.kind === "expected-fallback" && count > 1) return;
+
+  const rendered = renderEvent(event, count);
+  if (event.severity === "error") {
+    console.error(rendered);
+    return;
+  }
+  if (event.severity === "warning") {
+    console.warn(rendered);
+    return;
+  }
+  console.log(rendered);
+}
+
+export function getPipelineLogEvents(): PipelineLogEvent[] {
+  return getState().events.map((event) => ({ ...event }));
+}

package/src/ontology/capabilities/lead.prepare.yaml

@@ -0,0 +1,44 @@
+id: lead.prepare
+version: 1
+kind: action
+sideEffect: none
+title:
+  de: Anfrage prüfen
+  en: Preview a lead
+description:
+  de: "Prüft eine Kontaktanfrage (Name, E-Mail, Nachricht) ohne sie abzusenden — liefert eine draftId, die als Idempotency-Key eines späteren lead.submit dient. Nebenwirkungsfrei: es wird nichts zugestellt."
+  en: "Validates a contact request (name, email, message) without submitting it — returns a draftId usable as the Idempotency-Key of a later lead.submit. Side-effect-free: nothing is dispatched."
+input:
+  type: object
+  required: [name, email, message]
+  additionalProperties: false
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 200
+    email:
+      type: string
+      format: email
+      maxLength: 254
+    message:
+      type: string
+      minLength: 1
+      maxLength: 5000
+output:
+  type: object
+  required: [valid, draftId]
+  additionalProperties: false
+  properties:
+    valid:
+      type: boolean
+    draftId:
+      type: string
+      minLength: 71
+      maxLength: 71
+requires:
+  entitlements: [agent.actions]
+  sections: [send-message]
+limits:
+  perMinutePerIp: 10
+  maxPayloadBytes: 10240

package/src/ontology/capabilities/lead.submit.yaml

@@ -1,6 +1,7 @@
 id: lead.submit
-version: 1
+version: 2
 kind: action
+sideEffect: write
 title:
   de: Anfrage senden
   en: Submit a lead
@@ -26,11 +27,22 @@ input:
       maxLength: 5000
 output:
   type: object
-  required: [accepted]
+  required: [receiptId, status, duplicate, submittedAt]
   additionalProperties: false
   properties:
-    accepted:
+    receiptId:
+      type: string
+      format: uuid
+    status:
+      type: string
+      minLength: 1
+      maxLength: 16
+    duplicate:
       type: boolean
+    submittedAt:
+      type: string
+      minLength: 20
+      maxLength: 32
 integration:
   eventKind: lead
   source: agent
@@ -42,3 +54,8 @@ humanEquivalent:
 limits:
   perMinutePerIp: 3
   maxPayloadBytes: 10240
+agentGuidance:
+  sideEffect: write
+  whenToUse: "a visitor wants to contact the business — a question, a request, or a booking inquiry that needs a human reply."
+  whenNotToUse: "the visitor only needs information already published on the site — answer from the knowledge files or search instead of creating a lead."
+  retrySemantics: "safe to retry with the same Idempotency-Key — a repeated submission returns the original receipt instead of creating a duplicate lead."

package/src/ontology/operations/index.ts

@@ -158,11 +158,17 @@ export {
   integrationManifestSchema,
   integrationNullingSchema,
   notausgangManifestSchema,
+  notausgangEvidenceArtifactSchema,
+  notausgangEvidenceVerdictSchema,
+  notausgangFeatureNoteSchema,
 } from "./notausgang.ts";
 export type {
   IntegrationSecretLocation,
   IntegrationManifest,
   IntegrationNulling,
+  NotausgangEvidenceArtifact,
+  NotausgangEvidenceVerdict,
+  NotausgangFeatureNote,
   NotausgangManifest,
 } from "./notausgang.ts";
 

package/src/ontology/operations/notausgang.ts

@@ -36,6 +36,36 @@ export const integrationNullingSchema = z.object({
   ),
 });
 
+// RFC-1120: per-artifact record inside an evidence bundle verdict
+export const notausgangEvidenceArtifactSchema = z.object({
+  itemKey: z.string().min(1),
+  filename: z.string().min(1).optional(),
+  sha256: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
+  recordedSha256: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
+  r2Path: z.string().min(1).optional(),
+  external: z.boolean().optional(),
+  url: z.string().min(1).optional(),
+});
+
+// RFC-1120: per-source verdict — "bundled" | "external-reference" | "excluded:<reason>"
+export const notausgangEvidenceVerdictSchema = z.object({
+  verdict: z.string().regex(/^(bundled|external-reference|excluded:.+)$/),
+  artifacts: z.array(notausgangEvidenceArtifactSchema).optional(),
+});
+
+// RFC-1120: dynamic-feature disclosure entry
+export const notausgangFeatureNoteSchema = z.object({
+  feature: z.string().min(1),
+  verdict: z.enum(["static-ok", "frozen-at-export", "needs-backend"]),
+  detail: z.string(),
+});
+
 export const notausgangManifestSchema = z.object({
   schemaVersion: z.string().min(1),
   systemId: z.string().regex(STERNSYSTEM_ID_REGEX),
@@ -56,9 +86,23 @@ export const notausgangManifestSchema = z.object({
   distHash: z.string(),
   siteHash: z.string(),
   bordbuchHash: z.string(),
+  // RFC-1120: optional in schema (granular NA-* rules report absence);
+  // mandatory in packages produced by notausgang.export.
+  evidence: z.record(z.string(), notausgangEvidenceVerdictSchema).optional(),
+  features: z.array(notausgangFeatureNoteSchema).optional(),
+  verifier: z
+    .object({
+      script: z.literal("verify.py"),
+      runtime: z.literal("python3-stdlib"),
+      manifestFile: z.literal("notausgang-manifest.json"),
+    })
+    .optional(),
 });
 
 export type IntegrationSecretLocation = z.infer<typeof integrationSecretLocationSchema>;
 export type IntegrationManifest = z.infer<typeof integrationManifestSchema>;
 export type IntegrationNulling = z.infer<typeof integrationNullingSchema>;
+export type NotausgangEvidenceArtifact = z.infer<typeof notausgangEvidenceArtifactSchema>;
+export type NotausgangEvidenceVerdict = z.infer<typeof notausgangEvidenceVerdictSchema>;
+export type NotausgangFeatureNote = z.infer<typeof notausgangFeatureNoteSchema>;
 export type NotausgangManifest = z.infer<typeof notausgangManifestSchema>;

package/src/ontology/schemas/capability.ts

@@ -15,6 +15,8 @@ lossless projection to both OpenAPI (RFC-0289) and MCP tool schemas (RFC-0290).
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0288: initial capability record schema.</item>
+  <item>RFC-1112: add sideEffect ("write"|"none"); integration + humanEquivalent become optional and are required unless sideEffect is "none".</item>
+  <item>RFC-1115: add optional agentGuidance block (sideEffect, whenToUse, whenNotToUse, retrySemantics) rendered into MCP tool descriptions and OpenAPI operation docs.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -80,6 +82,22 @@ const capabilityLimitsSchema = z
   })
   .strict();
 
+/**
+ * RFC-1115: model-oriented guidance rendered into MCP tool descriptions and
+ * OpenAPI operation docs. `sideEffect` restates the record-level sideEffect so
+ * the guidance block is self-contained — a superRefine keeps them consistent.
+ * `retrySemantics` describes the RFC-1112 Idempotency-Key contract
+ * descriptively; the mechanism stays owned by RFC-1112.
+ */
+const capabilityAgentGuidanceSchema = z
+  .object({
+    sideEffect: z.enum(["write", "none"]),
+    whenToUse: z.string().min(1),
+    whenNotToUse: z.string().min(1).optional(),
+    retrySemantics: z.string().min(1).optional(),
+  })
+  .strict();
+
 /** RFC-0288: one capability catalog record (packages/werkstatt-site/src/domain/ontology/capabilities/<id>.yaml). */
 export const capabilityRecordSchema = z
   .object({
@@ -90,15 +108,49 @@ export const capabilityRecordSchema = z
     /** Integer; bump on breaking input/output change (by RFC). */
     version: z.number().int().positive(),
     kind: z.literal("action"),
+    /**
+     * RFC-1112: "write" (default when absent) dispatches an IntegrationEvent;
+     * "none" marks a side-effect-free preview that validates input and returns
+     * a draftId without dispatching.
+     */
+    sideEffect: z.enum(["write", "none"]).optional(),
     title: localizedStringSchema,
     description: localizedStringSchema,
     input: capabilityInputOutputSchema,
     output: capabilityInputOutputSchema,
-    integration: capabilityIntegrationSchema,
+    integration: capabilityIntegrationSchema.optional(),
     requires: capabilityRequiresSchema,
-    humanEquivalent: capabilityHumanEquivalentSchema,
+    humanEquivalent: capabilityHumanEquivalentSchema.optional(),
     limits: capabilityLimitsSchema,
+    agentGuidance: capabilityAgentGuidanceSchema.optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((record, ctx) => {
+    // RFC-1115: agentGuidance.sideEffect must restate the effective record-level
+    // sideEffect (absent means "write") — contradictory declarations are drift.
+    const effectiveSideEffect = record.sideEffect ?? "write";
+    if (record.agentGuidance && record.agentGuidance.sideEffect !== effectiveSideEffect) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["agentGuidance", "sideEffect"],
+        message: `must match the record-level sideEffect ("${effectiveSideEffect}")`,
+      });
+    }
+    if (record.sideEffect === "none") return;
+    if (!record.integration) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["integration"],
+        message: 'required unless sideEffect is "none"',
+      });
+    }
+    if (!record.humanEquivalent) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["humanEquivalent"],
+        message: 'required unless sideEffect is "none"',
+      });
+    }
+  });
 
 export type CapabilityRecord = z.infer<typeof capabilityRecordSchema>;

package/src/passport/claim-sign.ts

@@ -0,0 +1,120 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1124: Fleet claim signing and verification — canonicalization and
+sign/verify wrappers for FleetClaim, built on the existing Ed25519
+signBytes/verifyBytes primitives from sign.ts. Analogous to dht-sign.ts
+but for the git-native fleet claims registry claim shape.
+</purpose>
+<non-goals>
+  <item>Do not handle key storage or management — private keys arrive as env vars.</item>
+  <item>Do not assemble W3C VC envelopes — claims use a simple signature string, not VCProof.</item>
+  <item>Do not modify sign.ts — this module wraps signBytes/verifyBytes.</item>
+  <item>Do not implement claim legitimacy rules (self-claim vs transfer claim) — that lives in the engine's claims-repo.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1124: initial fleet claim signing module — FleetClaim contract, claimBytes, signClaim, verifyClaim.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * @warpgogol/werkstatt-shared/passport/claim-sign — fleet claim signing (RFC-1124)
+ *
+ * Uses signBytes/verifyBytes from sign.ts with a dedicated canonicalization
+ * function for fleet claims. The signature field is excluded from
+ * canonicalization (it is computed over the claim data without the signature).
+ */
+
+import { fromHex } from "@warpgogol/werkstatt-shared/signing";
+import { signBytes, toMultibase, verifyBytes } from "./sign.ts";
+
+/**
+ * One signed claim file: claims/<system-id>.json in the fleet claims repo.
+ *
+ * The claim is self-contained for offline signature verification:
+ * `signerPublicKey` is embedded, so a verifier needs nothing but the claim
+ * file to check the signature. Legitimacy (is this signer allowed to claim?)
+ * is decided by the engine — self-claims sign with the creator key, transfer
+ * claims sign with the PREVIOUS creator's key and carry `authorizationHash`
+ * binding them to the bordbuch `handover` event.
+ */
+export interface FleetClaim {
+  /** SHA-256 of the canonical passport.json at claim time. */
+  passportHash: string;
+  systemId: string;
+  /** did:web-style creator identity from passport.creator.identity. */
+  creatorIdentity: string;
+  /** deriveInstanceId(creator.publicKey) — first 16 hex of sha256. */
+  instanceId: string;
+  /** ISO 8601 — LWW field. */
+  claimedAt: string;
+  /** Bordbuch tip hash at claim time. */
+  bordbuchHead: string;
+  /**
+   * Tombstone marker — non-null ONLY on a tombstone file: a claim explicitly
+   * superseded without a same-id successor (e.g. system-id migration).
+   * Normal replacement never writes a tombstone — the new claim replaces the
+   * file and git history is the supersession chain.
+   */
+  supersededBy: string | null;
+  /**
+   * Hex Ed25519 public key of the signer — same format as
+   * passport.creator.publicKey, so deriveInstanceId(signerPublicKey) matches
+   * instanceId for self-claims. Embedded so the claims repo is self-contained
+   * for offline verification. Equals the creator's key for self-claims;
+   * equals the PREVIOUS creator's key for transfer claims.
+   */
+  signerPublicKey: string;
+  /**
+   * Transfer claims only: sha256 of the handover-authorization.json that
+   * authorizes the creator change (matches bordbuch `handover` event
+   * metadata.authorizationHash). Null for self-claims.
+   */
+  authorizationHash: string | null;
+  /** Ed25519 signature over the canonical JSON of all fields above. */
+  signature: string;
+}
+
+/**
+ * FleetClaim without the signature field — the data that is actually signed.
+ */
+export type FleetClaimData = Omit<FleetClaim, "signature">;
+
+/**
+ * Produce canonical UTF-8 bytes from a fleet claim (excluding signature).
+ * DETERMINISM: identical inputs → identical bytes (sorted-key JSON, no whitespace).
+ */
+export function claimBytes(claim: FleetClaimData): Uint8Array {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(claim).sort()) {
+    sorted[key] = (claim as Record<string, unknown>)[key];
+  }
+  const canonical = JSON.stringify(sorted);
+  return new TextEncoder().encode(canonical);
+}
+
+/**
+ * Sign a fleet claim and return a multibase Ed25519 signature string.
+ *
+ * @param claim          — claim data (without signature)
+ * @param privateKeyHex  — 32-byte Ed25519 private key as hex (from env secret)
+ * @returns multibase base58btc signature string
+ */
+export async function signClaim(claim: FleetClaimData, privateKeyHex: string): Promise<string> {
+  return signBytes(privateKeyHex, claimBytes(claim));
+}
+
+/**
+ * Verify a fleet claim signature against the claim's embedded signerPublicKey.
+ *
+ * @param claim — full fleet claim (including signature)
+ * @returns true if signature is valid
+ */
+export async function verifyClaim(claim: FleetClaim): Promise<boolean> {
+  const { signature, ...claimData } = claim;
+  // signerPublicKey is hex (passport.creator.publicKey format); verifyBytes
+  // expects multibase — convert here so callers never juggle encodings.
+  const signerMultibase = toMultibase(fromHex(claim.signerPublicKey));
+  return verifyBytes(signerMultibase, claimBytes(claimData), signature);
+}

package/src/passport/index.ts

@@ -56,3 +56,6 @@ export type { IdentityCredentialSubject } from "./identity-sign.ts";
 
 export { dhtEntryBytes, signDhtEntry, verifyDhtEntry } from "./dht-sign.ts";
 export type { DHTEntryData } from "./dht-sign.ts";
+
+export { claimBytes, signClaim, verifyClaim } from "./claim-sign.ts";
+export type { FleetClaim, FleetClaimData } from "./claim-sign.ts";

package/src/plugin/plugin-contract.ts

@@ -95,7 +95,7 @@ export interface WerkstattPlugin {
   schema: "werkstatt/plugin@1";
   /** Plugin id: "werkstatt-site" | "werkstatt-phaser-game" | "werkstatt-godot-game". */
   id: string;
-  /** Forge stack profile id, e.g. "astro-typescript-turborepo". */
+  /** Forge stack profile id, e.g. "site". */
   profileId: string;
   /** Kernel modules the plugin contributes (validators, codegen, content, onboarding). */
   moduleLoaders: Record<string, () => Promise<KernelModule>>;

package/src/semantic/canonical-uri.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-  <purpose>RFC-1075: derive persistent canonical URIs for PBP entity envelopes from site origin and entity identity. Used for Linked Data @id fields in JSON-LD and llms-full.txt projections.</purpose>
+  <purpose>RFC-1075: derive persistent canonical URIs for PBP entity envelopes from site origin and entity identity. Used for Linked Data @id fields in JSON-LD and llms-full.txt projections. RFC-1115: URIs carry a .json suffix and are dereferenceable — agent.knowledge.generate emits a static JSON-LD document at each path.</purpose>
   <non-goals>
     <item>Does not validate that the entity ID is well-formed — callers are responsible for providing valid IDs.</item>
     <item>Does not perform URL normalization beyond trailing-slash removal on the site origin.</item>
@@ -8,23 +8,26 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-1075: initial — deriveCanonicalUri pure function for persistent entity @id URIs.</item>
+  <item>RFC-1115: canonical entity URIs gain a .json suffix and become dereferenceable — agent.knowledge.generate emits a JSON-LD document at each emitted path.</item>
 </CHANGE_SUMMARY>
 */
 
 /**
  * Entity types supported by the PBP canonical URI scheme.
  *
- * The URI path pattern is `/.well-known/entity/{type}/{id}` for typed entities
- * (e.g. offerings) and `/.well-known/entity/business` for the single business entity.
+ * The URI path pattern is `/.well-known/entity/{type}/{id}.json` for typed entities
+ * (e.g. offerings) and `/.well-known/entity/business.json` for the single business entity.
+ * RFC-1115: the .json suffix makes every URI dereferenceable on a static host —
+ * agent.knowledge.generate emits a JSON-LD document at each path.
  */
 export type CanonicalEntityType = "business" | "offering";
 
 /**
  * RFC-1075: derive a persistent canonical URI for a PBP entity.
  *
- * The URI follows the pattern:
- * - Business: `{siteOrigin}/.well-known/entity/business`
- * - Offering: `{siteOrigin}/.well-known/entity/offering/{entityId}`
+ * The URI follows the pattern (RFC-1115 — dereferenceable .json form):
+ * - Business: `{siteOrigin}/.well-known/entity/business.json`
+ * - Offering: `{siteOrigin}/.well-known/entity/offering/{entityId}.json`
  *
  * The `siteOrigin` is stripped of trailing slashes to produce a clean base.
  * When `siteOrigin` is absent or empty, the function returns `undefined` —
@@ -35,6 +38,17 @@ export type CanonicalEntityType = "business" | "offering";
  * @param entityId - The entity ID (required for `"offering"`, ignored for `"business"`)
  * @returns The canonical URI string, or `undefined` when `siteOrigin` is absent
  */
+/**
+ * Reduce a PBP entity id to the slug used in canonical entity URIs and file
+ * paths. Entity IDs are URIs (e.g. `https://warpgogol.com/id/offerings/automation`);
+ * the last non-empty path segment is the slug (`automation`). Plain slugs pass
+ * through unchanged. Single source for the id→slug mapping so the canonical
+ * `@id`, the emitted file path, and the fact-parity comparator stay consistent.
+ */
+export function canonicalEntitySlug(entityId: string): string {
+  return entityId.split("/").filter(Boolean).pop() ?? entityId;
+}
+
 export function deriveCanonicalUri(
   siteOrigin: string | undefined,
   type: CanonicalEntityType,
@@ -45,10 +59,16 @@ export function deriveCanonicalUri(
   const base = siteOrigin.replace(/\/+$/, "");
 
   if (type === "business") {
-    return `${base}/.well-known/entity/business`;
+    return `${base}/.well-known/entity/business.json`;
   }
 
   if (!entityId) return undefined;
 
-  return `${base}/.well-known/entity/offering/${entityId}`;
+  // Entity IDs are URIs (e.g. `https://warpgogol.com/id/offerings/automation`).
+  // Embedding the raw URI into the path produces a malformed double-scheme URI
+  // (`.../offering/https://warpgogol.com/...`) and a non-filesystem-safe path
+  // (`path.join` collapses `//` → `/`, breaking the @id = served-path parity).
+  const slug = canonicalEntitySlug(entityId);
+
+  return `${base}/.well-known/entity/offering/${slug}.json`;
 }

package/src/semantic/llms.ts

@@ -346,18 +346,26 @@ function formatMarkdownLinkRow(site: SemanticSiteModel, page: SemanticPageModel)
   return `- [${title}](${url}): ${summary}`;
 }
 
-export function buildLlmsIndex(site: SemanticSiteModel): string {
+export function buildLlmsIndex(site: SemanticSiteModel, opts?: { servesSsr?: boolean }): string {
   const indexPages = site.pages.filter(inIndex);
   const llmsFullUrl = canonicalStaticUrl("/llms-full.txt", { baseUrl: site.baseUrl });
   const siteDescription = site.organization.description ?? "";
 
   // RFC-0789: agent discovery links — omitted when agent.enabled is false.
+  // The MCP Server Card exists only when the deployment adapter serves SSR
+  // routes (interfaces.mcp is set) — callers pass servesSsr=false on static
+  // adapters so the card is not advertised (PUBTXT-07 honesty).
   const agentEnabled = site.agent?.enabled !== false;
+  const servesSsr = opts?.servesSsr !== false;
   const agentLinks = agentEnabled
     ? [
         `> Machine-readable Agent Surface (structured knowledge + capabilities): [agent.json](${canonicalStaticUrl("/.well-known/agent.json", { baseUrl: site.baseUrl })}).`,
         `> API discovery catalog (RFC 9727): [api-catalog](${canonicalStaticUrl("/.well-known/api-catalog", { baseUrl: site.baseUrl })}).`,
-        `> MCP Server Card (SEP-1649): [server-card.json](${canonicalStaticUrl("/.well-known/mcp/server-card.json", { baseUrl: site.baseUrl })}).`,
+        ...(servesSsr
+          ? [
+              `> MCP Server Card (SEP-1649): [server-card.json](${canonicalStaticUrl("/.well-known/mcp/server-card.json", { baseUrl: site.baseUrl })}).`,
+            ]
+          : []),
         `> OpenAPI 3.1 specification: [agent.openapi.json](${canonicalStaticUrl("/.well-known/agent.openapi.json", { baseUrl: site.baseUrl })}).`,
       ]
     : [];

package/src/semantic/tests/canonical-uri.test.ts

@@ -12,18 +12,30 @@ describe("RFC-1075 AC-4: deriveCanonicalUri is pure and deterministic", () => {
     expect(deriveCanonicalUri("", "offering", "off-1")).toBeUndefined();
   });
 
-  it("derives business URI without entityId", () => {
+  it("derives business URI without entityId — RFC-1115 .json form", () => {
     expect(deriveCanonicalUri("https://example.example", "business")).toBe(
-      "https://example.example/.well-known/entity/business",
+      "https://example.example/.well-known/entity/business.json",
     );
   });
 
-  it("derives offering URI with entityId", () => {
+  it("derives offering URI with entityId — RFC-1115 .json form", () => {
     expect(deriveCanonicalUri("https://example.example", "offering", "off-1")).toBe(
-      "https://example.example/.well-known/entity/offering/off-1",
+      "https://example.example/.well-known/entity/offering/off-1.json",
     );
   });
 
+  it("slugifies URI-form entityId to its last path segment", () => {
+    // PBP entity IDs are URIs; the canonical entity URI must embed a slug,
+    // not the raw URI (which would produce a double-scheme, non-FS-safe path).
+    expect(
+      deriveCanonicalUri(
+        "https://example.example",
+        "offering",
+        "https://example.example/id/offerings/automation",
+      ),
+    ).toBe("https://example.example/.well-known/entity/offering/automation.json");
+  });
+
   it("returns undefined for offering without entityId", () => {
     expect(deriveCanonicalUri("https://example.example", "offering")).toBeUndefined();
     expect(deriveCanonicalUri("https://example.example", "offering", "")).toBeUndefined();
@@ -31,10 +43,10 @@ describe("RFC-1075 AC-4: deriveCanonicalUri is pure and deterministic", () => {
 
   it("strips trailing slashes from siteOrigin", () => {
     expect(deriveCanonicalUri("https://example.example/", "business")).toBe(
-      "https://example.example/.well-known/entity/business",
+      "https://example.example/.well-known/entity/business.json",
     );
     expect(deriveCanonicalUri("https://example.example//", "business")).toBe(
-      "https://example.example/.well-known/entity/business",
+      "https://example.example/.well-known/entity/business.json",
     );
   });
 

package/src/signing/index.ts

@@ -1,7 +1,9 @@
 /*
 <MODULE_CONTRACT>
   <purpose>Barrel export for @warpgogol/werkstatt-shared/signing sub-path. Re-exports the Ed25519 signing core (key generation, sign/verify, signing types) sunk from @warpgogol/werkstatt-engine per RFC-1104.</purpose>
-  <non-goals>Does not re-export engine signing commands (signing-commands.ts stays in engine).</non-goals>
+  <non-goals>
+    <item>Does not re-export engine signing commands (signing-commands.ts stays in engine).</item>
+  </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-1104: initial barrel — signing core sunk from werkstatt-engine.</item>

package/src/stack/run-tool.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>runTool — the single subprocess seam for stack plugins (RFC-1100). Owns the
+<purpose>runTool — the single subprocess seam that lets stack plugins run external binaries (RFC-1100). Owns the
 shared prologue every external-binary call needs: dist/ preflight, required-env
 presence check, env merge, timeout, and error mapping to ToolResult. Production
 uses the default execFileSync adapter; tests inject a recording ToolExecutor so no
@@ -91,9 +91,7 @@ export function runTool(spec: ToolSpec, executor: ToolExecutor = execFileExecuto
     if (missing.length > 0) {
       return {
         success: false,
-        errors: missing.map(
-          (name) => `Required environment variable ${name} is not set`,
-        ),
+        errors: missing.map((name) => `Required environment variable ${name} is not set`),
         failedAt: "preflight",
       };
     }