@warpgogol/werkstatt-shared 0.7.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/werkstatt-shared",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "private": false,
   "type": "module",
   "engines": {
@@ -250,6 +250,10 @@
       "types": "./src/share/middleware/language-redirect.ts",
       "default": "./src/share/middleware/language-redirect.ts"
     },
+    "./share/middleware/access-protection": {
+      "types": "./src/share/middleware/access-protection.ts",
+      "default": "./src/share/middleware/access-protection.ts"
+    },
     "./share/offer-capacity": {
       "types": "./src/share/offer-capacity.ts",
       "default": "./src/share/offer-capacity.ts"
@@ -318,6 +322,14 @@
       "types": "./src/share/shared-context.ts",
       "default": "./src/share/shared-context.ts"
     },
+    "./share/slug": {
+      "types": "./src/share/slug/index.ts",
+      "default": "./src/share/slug/index.ts"
+    },
+    "./share/routes/template-filter": {
+      "types": "./src/share/routes/template-filter.ts",
+      "default": "./src/share/routes/template-filter.ts"
+    },
     "./share/string-utils": {
       "types": "./src/share/string-utils.ts",
       "default": "./src/share/string-utils.ts"
@@ -1331,15 +1343,6 @@
       "default": "./src/share/scripts/index.ts"
     }
   },
-  "scripts": {
-    "lint": "pnpm exec eslint \"src/**/*.ts\"",
-    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
-    "build": "pnpm exec tsc -p tsconfig.json --noEmit",
-    "build:check": "pnpm exec tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "pnpm exec tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -1349,10 +1352,13 @@
   ],
   "dependencies": {
     "@lordicon/element": "^2.3.1",
-    "@noble/ed25519": "^3.1.0",
+    "@warpgogol/werkstatt": "*",
     "ajv": "^8.20.0",
     "bs58": "^6.0.0",
+    "@sindresorhus/slugify": "^3.0.0",
+    "cyrillic-to-translit-js": "^3.2.1",
     "expr-eval": "^2.0.2",
+    "github-slugger": "^2.0.0",
     "hls.js": "^1.6.16",
     "lenis": "^1.3.25",
     "plyr": "^3.8.4",
@@ -1361,17 +1367,27 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@syrokomskyi/axiom-study": "*"
+    "@syrokomskyi/axiom-study": "link:../../../pipelines/packages/axiom/axiom-study"
   },
   "devDependencies": {
+    "@astrojs/markdown-remark": "^7.0.0",
     "@cloudflare/workers-types": "^5.20260801.1",
     "@types/node": "^24.0.0",
+    "@warpgogol/werkstatt": "*",
     "astro": "^7.2.0",
     "eslint": "^10.8.0",
     "fast-check": "^4.9.0",
+    "gsap": "^3.15.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "8.65.0",
     "vitest": "^4.1.10"
   },
-  "packageManager": "pnpm@11.10.0"
-}
+  "scripts": {
+    "lint": "pnpm exec eslint \"src/**/*.ts\"",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "build": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "build:check": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/checks/index.ts

@@ -16,6 +16,7 @@ export {
   passResult,
   failResult,
   resultFromViolations,
+  formatCounts,
 } from "./result-helpers.ts";
 
 export * from "./suppressions-config.ts";

package/src/checks/result-helpers.ts

@@ -16,16 +16,55 @@ ruleId = command; diagnosticsResult takes rich Diagnostic[] with registered ids.
 </CHANGE_SUMMARY>
 */
 
-import type { CheckResult, Diagnostic, KernelCommandResult } from "@warpgogol/werkstatt/kernel";
+import type {
+  CheckResult,
+  Diagnostic,
+  KernelCommandResult,
+  KernelNextStep,
+} from "@warpgogol/werkstatt/kernel";
+
+function defaultFailNextSteps(command: string): KernelNextStep[] {
+  return [
+    {
+      action: `Fix the error diagnostics reported by ${command} above, then re-run the pipeline`,
+      kind: "required",
+    },
+  ];
+}
+
+/**
+ * Format error/warning counts with proper pluralization and zero-omission.
+ *
+ * - `0, 0` → `""` (empty string — caller should omit)
+ * - `1, 0` → `"1 error"`
+ * - `0, 1` → `"1 warning"`
+ * - `2, 0` → `"2 errors"`
+ * - `2, 1` → `"2 errors, 1 warning"`
+ */
+export function formatCounts(errors: number, warnings: number): string {
+  const parts: string[] = [];
+  if (errors > 0) {
+    parts.push(`${errors} error${errors === 1 ? "" : "s"}`);
+  }
+  if (warnings > 0) {
+    parts.push(`${warnings} warning${warnings === 1 ? "" : "s"}`);
+  }
+  return parts.join(", ");
+}
 
 /**
  * RFC-0203: canonical result builder. Migrated checks emit `Diagnostic[]` with
  * registered rule ids instead of bare strings. Exit code is 1 when any
  * diagnostic is an error; warnings and info do not fail the pipeline.
+ *
+ * When `nextSteps` are not provided and the result has errors, a default
+ * agent-actionable nextStep is emitted: "Fix the error diagnostics … then
+ * re-run the pipeline".
  */
 export function diagnosticsResult(
   command: string,
   diagnostics: Diagnostic[],
+  nextSteps?: KernelNextStep[],
 ): KernelCommandResult<CheckResult> {
   const summary = {
     error: diagnostics.filter((d) => d.severity === "error").length,
@@ -34,10 +73,14 @@ export function diagnosticsResult(
   };
   const status: CheckResult["status"] =
     summary.error > 0 ? "fail" : summary.warning > 0 ? "warn" : "pass";
+  const resolvedNextSteps =
+    nextSteps ?? (summary.error > 0 ? defaultFailNextSteps(command) : undefined);
+  const counts = formatCounts(summary.error, summary.warning);
   return {
     data: { command, status, diagnostics, summary },
     exitCode: summary.error > 0 ? 1 : 0,
-    summary: `${command}: ${summary.error} error(s), ${summary.warning} warning(s)`,
+    summary: counts ? `[${command}] ${counts}` : `[${command}]`,
+    nextSteps: resolvedNextSteps,
   };
 }
 
@@ -58,11 +101,16 @@ function emptySummary(): CheckResult["summary"] {
  * Canonical success result. RFC-0203: emits an empty `CheckResult` (no
  * diagnostics) rather than the legacy `{ command, status, violations }` shape.
  */
-export function passResult(command: string, summary?: string): KernelCommandResult<CheckResult> {
+export function passResult(
+  command: string,
+  summary?: string,
+  nextSteps?: KernelNextStep[],
+): KernelCommandResult<CheckResult> {
   return {
     data: { command, status: "pass", diagnostics: [], summary: emptySummary() },
     exitCode: 0,
-    summary: summary ?? `${command}: OK`,
+    summary: summary ?? `[${command}] OK`,
+    nextSteps,
   };
 }
 
@@ -70,10 +118,14 @@ export function passResult(command: string, summary?: string): KernelCommandResu
  * Canonical failure result — always exits 1 (preserving the historical
  * failResult contract). RFC-0203: violation strings become error Diagnostics
  * keyed by the command name.
+ *
+ * When `nextSteps` are not provided, a default agent-actionable nextStep is
+ * emitted: "Fix the error diagnostics … then re-run the pipeline".
  */
 export function failResult(
   command: string,
   violations: string[],
+  nextSteps?: KernelNextStep[],
 ): KernelCommandResult<CheckResult> {
   const diagnostics = violationsToDiagnostics(command, violations);
   return {
@@ -84,7 +136,8 @@ export function failResult(
       summary: { error: diagnostics.length, warning: 0, info: 0 },
     },
     exitCode: 1,
-    summary: `${command}: ${violations.length} violation(s)`,
+    summary: `[${command}] ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
+    nextSteps: nextSteps ?? defaultFailNextSteps(command),
   };
 }
 
@@ -97,6 +150,7 @@ export function failResult(
 export function resultFromViolations(
   command: string,
   violations: string[],
+  nextSteps?: KernelNextStep[],
 ): KernelCommandResult<CheckResult> {
-  return violations.length > 0 ? failResult(command, violations) : passResult(command);
+  return violations.length > 0 ? failResult(command, violations, nextSteps) : passResult(command);
 }

package/src/checks/suppressions-config.ts

@@ -17,7 +17,32 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { parse as parseYaml } from "yaml";
-import type { Finding } from "@syrokomskyi/axiom-study";
+
+/**
+ * Minimal Finding shape matching @syrokomskyi/axiom-study's Finding interface.
+ * Defined locally so the package typechecks without axiom-study installed.
+ * See share/types/axiom-study.d.ts for the full canonical declaration.
+ */
+interface Finding {
+  findingId: string;
+  semanticFingerprint: { algorithm: "sha256"; digest: string; size: number; mediaType: string };
+  methodologyId: string;
+  ruleId: string;
+  affectedSubjectId: string;
+  title: string;
+  severity: "info" | "low" | "medium" | "high" | "critical";
+  evidence: Array<{
+    evidenceRef: {
+      artifactId: string;
+      rootDigest: { algorithm: "sha256"; digest: string; size: number; mediaType: string };
+      schema: string;
+    };
+    selector: string;
+    evidenceClass: string;
+  }>;
+  uncertainty: unknown[];
+  extension: Record<string, unknown>;
+}
 
 export const suppressionRuleSchema = z.object({
   ruleId: z.string().min(1),

package/src/content/system-manifest.ts

@@ -9,6 +9,7 @@ Stack-agnostic utility used by both engine and site plugin (RFC-0868).</purpose>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0868: extracted from werkstatt-site/src/content/system-manifest.ts.</item>
+  <item>RFC-0911: add seo?.anchorText?.extraStopPhrases for anchor-text stop-list extension.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -101,6 +102,13 @@ export interface SystemManifest {
       swapOrder?: boolean;
     };
   };
+  /** RFC-0911: SEO validator configuration extension point. */
+  seo?: {
+    anchorText?: {
+      /** Added to the built-in de/uk stop-list. */
+      extraStopPhrases?: Record<string, string[]>;
+    };
+  };
 }
 
 export interface SystemManifestLoadResult {

package/src/ontology/archetypes/index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "totalCount": 58,
+  "totalCount": 59,
   "entries": [
     {
       "id": "approach",
@@ -218,6 +218,18 @@
       "sourceFile": "packages/werkstatt-site/src/domain/ontology/archetypes/components/footer-promo.yaml",
       "layer": "component"
     },
+    {
+      "id": "gratitude",
+      "displayName": "Gratitude",
+      "semanticRole": "client-gratitude",
+      "version": "1.0.0",
+      "layoutHint": "card-grid",
+      "acceptedCosmicNames": [
+        "Gonggong"
+      ],
+      "sourceFile": "packages/werkstatt-site/src/domain/ontology/archetypes/sections/gratitude.yaml",
+      "layer": "section"
+    },
     {
       "id": "hero",
       "displayName": "Hero",
@@ -704,6 +716,7 @@
     "article-index",
     "audience-self-identification",
     "breadcrumbs",
+    "client-gratitude",
     "client-ownership-disclosure",
     "consent-gated-chat-launcher",
     "credits-gallery",
@@ -777,6 +790,7 @@
     "Elara": "@warpgogol/werkstatt-site/ui/sections/dynamic-status-block",
     "Atlas": "@warpgogol/werkstatt-site/ui/sections/faq-list",
     "Dione": "@warpgogol/werkstatt-site/ui/sections/final-cta",
+    "Gonggong": "@warpgogol/werkstatt-site/ui/sections/gratitude",
     "Europa": "@warpgogol/werkstatt-site/ui/sections/hero",
     "Phobos": "@warpgogol/werkstatt-site/ui/sections/hero-decision-card",
     "Ganymede": "@warpgogol/werkstatt-site/ui/sections/impact",
@@ -854,6 +868,7 @@
     "dynamic-status-block": "Elara",
     "faq-list": "Atlas",
     "final-cta": "Dione",
+    "gratitude": "Gonggong",
     "hero": "Europa",
     "hero-decision-card": "Phobos",
     "impact": "Ganymede",
@@ -935,6 +950,7 @@
     "Elara": "data-driven-status-indicator",
     "Atlas": "approach",
     "Dione": "final-cta",
+    "Gonggong": "client-gratitude",
     "Europa": "hero",
     "Phobos": "hero",
     "Ganymede": "impact",

package/src/ontology/schemas/page-entry.ts

@@ -66,14 +66,12 @@ const visibilityExprSchema: z.ZodType<unknown> = z.lazy(() =>
 export const BlockEntrySchema = z
   .object({
     /**
-     * Optional stable block identifier for analytics, anchor links, and
-     * block-level attribution. Must be kebab-case when provided.
-     * page.block.validate enforces uniqueness within a page.
+     * Mandatory stable block identifier for analytics, anchor links, and
+     * block-level attribution. Must be kebab-case. RFC-0914 makes this required.
+     * page.block.validate enforces uniqueness within a page (B-05).
+     * page.blocks.extract.validate enforces presence and format (BLOCK-ID-MISSING, BLOCK-ID-INVALID).
      */
-    id: z
-      .string()
-      .regex(/^[a-z0-9-]+$/, "Block id must be kebab-case")
-      .optional(),
+    id: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "Block id must be kebab-case"),
 
     /**
      * Cosmic name identifying the section/component for this block.

package/src/ontology/schemas/system/manifest.ts

@@ -17,6 +17,7 @@ import { systemSharedContextSchema, systemGrowthSchema } from "./growth.ts";
 import { systemReleaseSchema } from "./release.ts";
 import { systemTextSchema } from "./text.ts";
 import { systemIntegrationsSchema } from "./integrations.ts";
+import { systemVerificationSchema } from "./verification.ts";
 import { semanticPageTypeSchema, articleMetadataSchema, pageOutputSchema } from "./page-output.ts";
 
 /**
@@ -482,6 +483,13 @@ export const systemManifestSchema = z.object({
         .optional(),
     })
     .optional(),
+
+  /**
+   * Search engine verification config (RFC-0909).
+   * Declares per-engine verification method and token.
+   * When absent, search.verification.validate emits SEARCH-VERIFY-01.
+   */
+  verification: systemVerificationSchema.optional(),
 });
 
 export type SystemManifest = z.infer<typeof systemManifestSchema>;

package/src/ontology/schemas/system/verification.ts

@@ -0,0 +1,40 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Verification block schema (RFC-0909) for the system manifest.
+Declares per-search-engine verification method and token for Google Search Console.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0909: initial verification schema for search engine verification surface.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+/**
+ * The `verification:` block in src/content/system.md. Declares per-search-engine
+ * verification method and token so that search.verification.validate can enforce
+ * the declaration and the layout can emit the google-site-verification meta tag.
+ *
+ * Example src/content/system.md verification block:
+ *   verification:
+ *     google:
+ *       method: dns-txt
+ *       token: google-site-verification=abc123...
+ */
+export const systemVerificationSchema = z.object({
+  google: z
+    .object({
+      method: z.enum(["dns-txt", "meta-tag"]),
+      /**
+       * dns-txt: full TXT value "google-site-verification=...".
+       * meta-tag: content attribute of the google-site-verification meta tag.
+       */
+      token: z.string().min(1),
+    })
+    .optional(),
+});
+
+export type SystemVerification = z.infer<typeof systemVerificationSchema>;

package/src/passport/sign.ts

@@ -1,5 +1,5 @@
 /* <MODULE_CONTRACT>
-<purpose>Facilitates Ed25519 key generation, signing, and verification for verifiable credentials.</purpose>
+<purpose>Facilitates Ed25519 key generation, signing, and verification for verifiable credentials via shared signing core (RFC-0921).</purpose>
 <non-goals>
   <item>Do not handle raw key storage or management.</item>
   <item>Do not perform network operations or external API calls.</item>
@@ -8,6 +8,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+  <item>RFC-0921: delegate Ed25519 sign/verify/keygen to shared signing core (@warpgogol/werkstatt/signing). Remove @noble/ed25519 import.</item>
 </CHANGE_SUMMARY> */
 
 /**
@@ -24,8 +25,14 @@
  * - This module never logs, writes, or returns private key material.
  */
 
-import * as ed from "@noble/ed25519";
 import bs58 from "bs58";
+import {
+  generateKeyPair as signingGenerateKeyPair,
+  signBytes as signingSignBytes,
+  verifyBytes as signingVerifyBytes,
+  fromHex,
+  toHex,
+} from "@warpgogol/werkstatt/signing";
 import type { VCProof, VerifiableCredential } from "./schema.ts";
 
 // ---------------------------------------------------------------------------
@@ -90,12 +97,11 @@ export async function generateKeypair(): Promise<{
   publicKeyBytes: Uint8Array;
   publicKeyMultibase: string;
 }> {
-  const privateKeyBytes = ed.utils.randomSecretKey();
-  const publicKeyBytes = await ed.getPublicKeyAsync(privateKeyBytes);
+  const keyPair = await signingGenerateKeyPair();
   return {
-    privateKeyHex: Buffer.from(privateKeyBytes).toString("hex"),
-    publicKeyBytes,
-    publicKeyMultibase: toMultibase(publicKeyBytes),
+    privateKeyHex: toHex(keyPair.privateKey),
+    publicKeyBytes: keyPair.publicKey,
+    publicKeyMultibase: toMultibase(keyPair.publicKey),
   };
 }
 
@@ -110,7 +116,7 @@ export async function generateKeypair(): Promise<{
  * @param privateKeyHex — 32-byte Ed25519 private key as hex (from env secret)
  * @param verificationMethod — DID key reference (e.g. "did:web:example.org#key-v1")
  */
-// @ai-invariant: signCredential uses @noble/ed25519. Private keys arrive
+// @ai-invariant: signCredential uses the shared signing core (RFC-0921). Private keys arrive
 // exclusively as hex env vars — never logged, written to disk, or returned.
 // The signed output is a W3C VC with Ed25519Signature2020 proof.
 
@@ -119,9 +125,9 @@ export async function signCredential(
   privateKeyHex: string,
   verificationMethod: string,
 ): Promise<VCProof> {
-  const privateKeyBytes = new Uint8Array(Buffer.from(privateKeyHex, "hex"));
+  const privateKeyBytes = fromHex(privateKeyHex);
   const message = credentialBytes(subject);
-  const signatureBytes = await ed.signAsync(message, privateKeyBytes);
+  const signatureBytes = await signingSignBytes(privateKeyBytes, message);
 
   return {
     type: "Ed25519Signature2020",
@@ -153,7 +159,7 @@ export async function verifyCredential(
     const publicKeyBytes = fromMultibase(publicKeyMultibase);
     const signatureBytes = fromMultibase(proof.proofValue);
     const message = credentialBytes(subject);
-    return await ed.verifyAsync(signatureBytes, message, publicKeyBytes);
+    return await signingVerifyBytes(publicKeyBytes, message, signatureBytes);
   } catch {
     return false;
   }
@@ -173,8 +179,8 @@ export async function verifyCredential(
  * @param message       — canonical bytes to sign
  */
 export async function signBytes(privateKeyHex: string, message: Uint8Array): Promise<string> {
-  const privateKeyBytes = new Uint8Array(Buffer.from(privateKeyHex, "hex"));
-  const signatureBytes = await ed.signAsync(message, privateKeyBytes);
+  const privateKeyBytes = fromHex(privateKeyHex);
+  const signatureBytes = await signingSignBytes(privateKeyBytes, message);
   return toMultibase(signatureBytes);
 }
 
@@ -190,7 +196,7 @@ export async function verifyBytes(
   try {
     const publicKeyBytes = fromMultibase(publicKeyMultibase);
     const signatureBytes = fromMultibase(signatureMultibase);
-    return await ed.verifyAsync(signatureBytes, message, publicKeyBytes);
+    return await signingVerifyBytes(publicKeyBytes, message, signatureBytes);
   } catch {
     return false;
   }

package/src/share/agent/ard-catalog.ts

@@ -0,0 +1,133 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+ARD (Agentic Resource Discovery) ai-catalog.json projection. Pure, dependency-free
+formatter that projects a site's Agent Surface Manifest into the ai-catalog data model
+for /.well-known/ai-catalog.json. No I/O — the kernel command loads the manifest and
+passes it here.
+</purpose>
+<non-goals>
+  <item>Do not read files — callers load and pass the manifest.</item>
+  <item>Do not duplicate logic from api-catalog or mcp-card — this is a separate spec.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial ARD ai-catalog.json projection for isitagentready.com ARD check.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { AgentSurfaceManifest } from "./manifest.ts";
+
+/** ARD ai-catalog entry — one per discoverable resource. */
+export interface ArdCatalogEntry {
+  identifier: string;
+  displayName: string;
+  type: string;
+  url: string;
+  representativeQueries: string[];
+}
+
+/** ARD ai-catalog host object. */
+export interface ArdCatalogHost {
+  displayName: string;
+  identifier: string;
+}
+
+/** ARD ai-catalog top-level document. */
+export interface ArdCatalog {
+  specVersion: string;
+  host: ArdCatalogHost;
+  entries: ArdCatalogEntry[];
+}
+
+/**
+ * Pure: project Agent Surface Manifest into ARD ai-catalog.json.
+ * Deterministic — entries are sorted by identifier for byte-identical output (DNA-58).
+ */
+export function buildArdCatalog(
+  manifest: AgentSurfaceManifest,
+  hostDisplayName?: string,
+): ArdCatalog {
+  const domain = manifest.baseUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const displayName = hostDisplayName ?? manifest.site;
+
+  const entries: ArdCatalogEntry[] = [];
+
+  // MCP server card entry
+  if (manifest.interfaces.mcp) {
+    entries.push({
+      identifier: `urn:air:${domain}:server:mcp`,
+      displayName: "MCP Server",
+      type: "application/mcp-server-card+json",
+      url: "/.well-known/mcp/server-card.json",
+      representativeQueries: [
+        "What tools are available on this MCP server",
+        "List MCP server capabilities and endpoints",
+      ],
+    });
+  }
+
+  // A2A Agent Card entry
+  entries.push({
+    identifier: `urn:air:${domain}:agent:a2a`,
+    displayName: "A2A Agent Card",
+    type: "application/a2a+json",
+    url: "/.well-known/agent-card.json",
+    representativeQueries: [
+      "What agent capabilities does this site offer",
+      "Get the A2A agent card for this service",
+    ],
+  });
+
+  // OpenAPI entry
+  if (manifest.interfaces.openapi) {
+    entries.push({
+      identifier: `urn:air:${domain}:api:openapi`,
+      displayName: "OpenAPI Specification",
+      type: "application/vnd.oai.openapi+json",
+      url: manifest.interfaces.openapi,
+      representativeQueries: [
+        "What API endpoints are available on this site",
+        "Get the OpenAPI specification for agent integration",
+      ],
+    });
+  }
+
+  // Agent Surface Manifest entry
+  entries.push({
+    identifier: `urn:air:${domain}:manifest:agent-surface`,
+    displayName: "Agent Surface Manifest",
+    type: "application/json",
+    url: "/.well-known/agent.json",
+    representativeQueries: [
+      "What agent discovery endpoints does this site provide",
+      "Get the agent surface manifest for this site",
+    ],
+  });
+
+  // Knowledge domain entries
+  for (const ref of manifest.knowledge) {
+    entries.push({
+      identifier: `urn:air:${domain}:knowledge:${ref.domain}`,
+      displayName: `${ref.domain.charAt(0).toUpperCase() + ref.domain.slice(1)} Knowledge`,
+      type: "application/json",
+      url: ref.url,
+      representativeQueries: [
+        `What ${ref.domain} information is available on this site`,
+        `Get structured ${ref.domain} data for agent consumption`,
+      ],
+    });
+  }
+
+  // Sort entries by identifier for deterministic output
+  entries.sort((a, b) => a.identifier.localeCompare(b.identifier));
+
+  return {
+    specVersion: "1.0",
+    host: {
+      displayName,
+      identifier: `did:web:${domain}`,
+    },
+    entries,
+  };
+}

package/src/share/agent/index.ts

@@ -27,3 +27,4 @@ export * from "./fleet-catalog.ts";
 export * from "./api-catalog.ts";
 export * from "./mcp-card.ts";
 export * from "./dns-aid.ts";
+export * from "./ard-catalog.ts";