@warpgogol/werkstatt-shared 0.13.0 → 0.14.0

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

@@ -12,6 +12,7 @@ No I/O — the kernel command loads the manifest and passes it here.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0783: initial API Catalog linkset+json projection.</item>
+  <item>RFC-0954: add search endpoint link when interfaces.search is non-null.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -71,6 +72,10 @@ export function buildApiCatalog(manifest: AgentSurfaceManifest): ApiCatalog {
     entry["service"] = [{ href: manifest.interfaces.mcp.url, type: "application/json" }];
   }
 
+  if (manifest.interfaces.search) {
+    entry["search"] = [{ href: manifest.interfaces.search.url, type: "application/json" }];
+  }
+
   entry["service-doc"] = [{ href: manifest.interfaces.llms, type: "text/plain" }];
 
   return { linkset: [entry] };

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

@@ -105,6 +105,20 @@ export function buildArdCatalog(
     ],
   });
 
+  // Semantic search endpoint entry
+  if (manifest.interfaces.search) {
+    entries.push({
+      identifier: `urn:air:${domain}:api:search`,
+      displayName: "Semantic Search",
+      type: "application/json",
+      url: manifest.interfaces.search.url,
+      representativeQueries: [
+        "Search this site for relevant content",
+        "Find pages matching a natural language query",
+      ],
+    });
+  }
+
   // Knowledge domain entries
   for (const ref of manifest.knowledge) {
     entries.push({

package/src/share/agent/index.ts

@@ -14,6 +14,7 @@ here (knowledge, capability, openapi, proof) and re-export them from this barrel
   <item>RFC-0292: re-export fleet-catalog module.</item>
   <item>RFC-0783: re-export api-catalog and mcp-card modules.</item>
   <item>RFC-0786: re-export dns-aid module.</item>
+  <item>RFC-0954: re-export search module.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -28,3 +29,4 @@ export * from "./api-catalog.ts";
 export * from "./mcp-card.ts";
 export * from "./dns-aid.ts";
 export * from "./ard-catalog.ts";
+export * from "./search.ts";

package/src/share/agent/manifest.ts

@@ -14,6 +14,7 @@ two runs on unchanged input are byte-identical (AS-7).
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0286: initial manifest contract and pure builder.</item>
+  <item>RFC-0954: add search interface to AgentSurfaceManifest.interfaces.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -54,6 +55,7 @@ export interface AgentSurfaceManifest {
     twins: { pattern: string } | null;
     openapi: string | null;
     mcp: { url: string; protocolVersion: string } | null;
+    search: { url: string; model: string; dimensions: number } | null;
   };
   /** Null until agent.surface.sign signs it (RFC-0308) or when no key material exists. */
   proof: AgentSurfaceProof | null;
@@ -68,6 +70,7 @@ export interface AgentSurfaceManifestInput {
   hasTwins?: boolean;
   openapiUrl?: string | null;
   mcp?: { url: string; protocolVersion: string } | null;
+  search?: { url: string; model: string; dimensions: number } | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -91,10 +94,29 @@ export function canonicalJson(value: unknown): string {
   return JSON.stringify(sortKeysDeep(value));
 }
 
+/**
+ * sha256 hex over the canonical JSON of `doc` with `contentHash`, `proof`, and any
+ * additional `excludeFields` removed. All signed manifest hash functions MUST use
+ * this helper to ensure the `proof` field is always excluded — a missing exclusion
+ * causes contentHash drift after signing (AGS-SEARCH-07 pattern).
+ */
+export function computeSignedContentHash(
+  doc: Record<string, unknown>,
+  excludeFields: string[] = [],
+): string {
+  const exclusions = new Set(["contentHash", "proof", ...excludeFields]);
+  const rest: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(doc)) {
+    if (!exclusions.has(key)) {
+      rest[key] = value;
+    }
+  }
+  return createHash("sha256").update(canonicalJson(rest), "utf8").digest("hex");
+}
+
 /** sha256 hex over the canonical JSON of `doc` with `contentHash` and `proof` removed. */
 export function computeAgentManifestContentHash(doc: Record<string, unknown>): string {
-  const { contentHash: _contentHash, proof: _proof, ...rest } = doc;
-  return createHash("sha256").update(canonicalJson(rest), "utf8").digest("hex");
+  return computeSignedContentHash(doc);
 }
 
 // ---------------------------------------------------------------------------
@@ -118,6 +140,7 @@ export function buildAgentSurfaceManifest(input: AgentSurfaceManifestInput): Age
       twins: input.hasTwins ? { pattern: "/**.md" } : null,
       openapi: input.openapiUrl ?? null,
       mcp: input.mcp ?? null,
+      search: input.search ?? null,
     },
     proof: null,
   };

package/src/share/agent/mcp-card.ts

@@ -12,6 +12,7 @@ No I/O — the kernel command loads the manifest and passes it here.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0783: initial MCP Server Card projection.</item>
+  <item>RFC-0954: include search tool in serverInfo description when interfaces.search is non-null.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -48,6 +49,9 @@ export function buildMcpServerCard(manifest: AgentSurfaceManifest): McpServerCar
     serverInfo: {
       name: `${manifest.site}-agent-gate`,
       version: manifest.surfaceVersion,
+      ...(manifest.interfaces.search
+        ? { description: "Agent gate with MCP tools and semantic search" }
+        : {}),
     },
     transport: {
       type: "streamable-http",

package/src/share/agent/openapi.ts

@@ -15,6 +15,7 @@ copied verbatim (AGO-04 enforces this).
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0289: initial OpenAPI projection.</item>
+  <item>RFC-0954: add /api/agent/search path with dynamic lang enum from manifest.languages.supported.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -33,6 +34,13 @@ export interface OpenApiOperation {
   operationId: string;
   summary?: string;
   tags: string[];
+  parameters?: Array<{
+    name: string;
+    in: string;
+    required?: boolean;
+    schema: Record<string, unknown>;
+    description?: string;
+  }>;
   requestBody?: {
     required: true;
     content: { "application/json": { schema: OpenApiSchemaObject } };
@@ -136,6 +144,76 @@ export function formatAgentOpenApi(
     };
   }
 
+  if (manifest.interfaces.search) {
+    const searchSchema: OpenApiSchemaObject = {
+      type: "object",
+      required: ["query", "results", "tookMs"],
+      properties: {
+        query: { type: "string" },
+        results: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              chunk: { type: "object" },
+              score: { type: "number" },
+            },
+          },
+        },
+        tookMs: { type: "number" },
+      },
+    };
+    componentSchemas["search-response"] = searchSchema;
+    const langEnum = manifest.languages.supported;
+    paths[manifest.interfaces.search.url] = {
+      get: {
+        operationId: "search.query",
+        summary: "Semantic search over site content",
+        tags: ["search"],
+        responses: {
+          "200": {
+            description: "Search results",
+            content: {
+              "application/json": { schema: { $ref: "#/components/schemas/search-response" } },
+            },
+          },
+          "400": { description: "Invalid query" },
+          "503": { description: "Search index not available" },
+        },
+        parameters: [
+          {
+            name: "q",
+            in: "query",
+            required: true,
+            schema: { type: "string", maxLength: 1000 },
+            description: "Natural language search query",
+          },
+          {
+            name: "lang",
+            in: "query",
+            required: false,
+            schema: { type: "string", enum: langEnum },
+            description: "Filter by language",
+          },
+          {
+            name: "type",
+            in: "query",
+            required: false,
+            schema: { type: "string", enum: ["page", "knowledge", "faq", "prose"] },
+            description: "Filter by content type",
+          },
+          {
+            name: "topK",
+            in: "query",
+            required: false,
+            schema: { type: "integer", default: 5, maximum: 20 },
+            description: "Number of results to return",
+          },
+        ],
+      },
+    };
+  }
+
   const doc: OpenApiDocument = {
     openapi: "3.1.0",
     info: {

package/src/share/agent/search.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildSearchManifest,
+  computeSearchManifestContentHash,
+  SEARCH_EMBEDDING_MODEL,
+  SEARCH_EMBEDDING_DIMENSIONS,
+  SEARCH_MANIFEST_SCHEMA_VERSION,
+  SEARCH_CHUNK_TEXT_MAX_LENGTH,
+  isNonKnowledgeFile,
+  NON_KNOWLEDGE_FILES,
+  type SearchChunk,
+} from "./search.ts";
+
+const baseChunk: SearchChunk = {
+  id: "de:/about:block-intro",
+  url: "/about",
+  lang: "de",
+  type: "page",
+  blockId: "block-intro",
+  heading: "About",
+  text: "About the company",
+};
+
+describe("buildSearchManifest", () => {
+  it("produces a manifest with correct schema version and model", () => {
+    const manifest = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    expect(manifest.schema).toBe(SEARCH_MANIFEST_SCHEMA_VERSION);
+    expect(manifest.model).toBe(SEARCH_EMBEDDING_MODEL);
+    expect(manifest.dimensions).toBe(SEARCH_EMBEDDING_DIMENSIONS);
+  });
+
+  it("sorts chunks by id for deterministic output", () => {
+    const chunkB: SearchChunk = { ...baseChunk, id: "de:/about:block-zzz" };
+    const chunkA: SearchChunk = { ...baseChunk, id: "de:/about:block-aaa" };
+    const manifest = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [chunkB, chunkA],
+    });
+    expect(manifest.chunks[0].id).toBe("de:/about:block-aaa");
+    expect(manifest.chunks[1].id).toBe("de:/about:block-zzz");
+  });
+
+  it("is deterministic — same input produces same contentHash regardless of chunk order", () => {
+    const chunkA: SearchChunk = { ...baseChunk, id: "aaa" };
+    const chunkB: SearchChunk = { ...baseChunk, id: "bbb" };
+    const m1 = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [chunkA, chunkB],
+    });
+    const m2 = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-28T00:00:00Z",
+      chunks: [chunkB, chunkA],
+    });
+    expect(m1.contentHash).toBe(m2.contentHash);
+  });
+
+  it("excludes generatedAt from contentHash", () => {
+    const m1 = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    const m2 = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-28T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    expect(m1.contentHash).toBe(m2.contentHash);
+    expect(m1.generatedAt).not.toBe(m2.generatedAt);
+  });
+
+  it("produces different contentHash when chunks change", () => {
+    const m1 = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    const m2 = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [{ ...baseChunk, text: "Different text" }],
+    });
+    expect(m1.contentHash).not.toBe(m2.contentHash);
+  });
+
+  it("produces different contentHash when site changes", () => {
+    const m1 = buildSearchManifest({
+      site: "site-a",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    const m2 = buildSearchManifest({
+      site: "site-b",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    expect(m1.contentHash).not.toBe(m2.contentHash);
+  });
+});
+
+describe("computeSearchManifestContentHash", () => {
+  it("matches the hash produced by buildSearchManifest", () => {
+    const manifest = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    const recomputed = computeSearchManifestContentHash(manifest);
+    expect(recomputed).toBe(manifest.contentHash);
+  });
+
+  it("excludes proof from contentHash", () => {
+    const manifest = buildSearchManifest({
+      site: "test-site",
+      model: SEARCH_EMBEDDING_MODEL,
+      dimensions: SEARCH_EMBEDDING_DIMENSIONS,
+      generatedAt: "2026-08-27T00:00:00Z",
+      chunks: [baseChunk],
+    });
+    const withProof = {
+      ...manifest,
+      proof: {
+        type: "Ed25519Signature2020",
+        created: "2026-08-27T00:00:00Z",
+        verificationMethod: "did:web:example.com#key-v1",
+        proofPurpose: "assertionMethod",
+        proofValue: "zFakeProofValue",
+      },
+    };
+    expect(computeSearchManifestContentHash(withProof)).toBe(manifest.contentHash);
+  });
+});
+
+describe("constants", () => {
+  it("SEARCH_CHUNK_TEXT_MAX_LENGTH is 2000", () => {
+    expect(SEARCH_CHUNK_TEXT_MAX_LENGTH).toBe(2000);
+  });
+});
+
+describe("isNonKnowledgeFile", () => {
+  it("returns true for search-manifest.json", () => {
+    expect(isNonKnowledgeFile("search-manifest.json")).toBe(true);
+  });
+
+  it("returns false for knowledge domain files", () => {
+    expect(isNonKnowledgeFile("company.json")).toBe(false);
+    expect(isNonKnowledgeFile("offer.json")).toBe(false);
+    expect(isNonKnowledgeFile("faq.json")).toBe(false);
+  });
+
+  it("returns false for arbitrary filenames", () => {
+    expect(isNonKnowledgeFile("foo.json")).toBe(false);
+    expect(isNonKnowledgeFile("readme.md")).toBe(false);
+  });
+
+  it("NON_KNOWLEDGE_FILES contains search-manifest.json", () => {
+    expect(NON_KNOWLEDGE_FILES).toContain("search-manifest.json");
+  });
+});

package/src/share/agent/search.ts

@@ -0,0 +1,164 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0954: shared types and pure helpers for the agent semantic search capability.
+Defines the search manifest shape (build-time output), query/response contracts
+(runtime API), and pinned embedding model constants. Pure, deterministic — no I/O,
+no timestamps in the hash payload.
+</purpose>
+<non-goals>
+  <item>Do not read files or embed text — callers (kernel commands) load content and
+        call buildSearchManifest with already-extracted chunks.</item>
+  <item>Do not call Workers AI or Vectorize — runtime logic lives in agent-gate/astro.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0954: initial search manifest contract, query/response types, and pure builder.</item>
+  <item>m000101: add NON_KNOWLEDGE_FILES and isNonKnowledgeFile for shared non-knowledge-file exclusion.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { computeSignedContentHash } from "./manifest.ts";
+
+// ---------------------------------------------------------------------------
+// Pinned embedding model constants (RFC-0954 §Embedding model)
+// ---------------------------------------------------------------------------
+
+/** Cloudflare Workers AI embedding model for semantic search (multilingual, 1024 dims). */
+export const SEARCH_EMBEDDING_MODEL = "@cf/baai/bge-m3";
+
+/** Vector dimensions for the pinned embedding model. */
+export const SEARCH_EMBEDDING_DIMENSIONS = 1024;
+
+/** Maximum number of results per query. */
+export const SEARCH_MAX_TOP_K = 20;
+
+/** Default number of results per query. */
+export const SEARCH_DEFAULT_TOP_K = 5;
+
+/** Maximum character length for a chunk's `text` field (truncated before embedding). */
+export const SEARCH_CHUNK_TEXT_MAX_LENGTH = 2000;
+
+/** Schema version for the search manifest. */
+export const SEARCH_MANIFEST_SCHEMA_VERSION = "1";
+
+/** Static asset path for the generated search manifest. */
+export const SEARCH_MANIFEST_PATH = "public/api/agent/v1/search-manifest.json";
+
+/**
+ * Files that live in the knowledge directory (`public/api/agent/v1/`) but are NOT
+ * knowledge envelopes. Used by `agent.knowledge.validate`, `agent.manifest.generate`,
+ * `agent.surface.validate`, and `agent.search.manifest.generate` to skip non-knowledge
+ * artifacts when iterating knowledge domain files.
+ */
+export const NON_KNOWLEDGE_FILES = ["search-manifest.json"] as const;
+
+/** Returns true if `filename` is a non-knowledge file that lives in the knowledge directory. */
+export function isNonKnowledgeFile(filename: string): boolean {
+  return (NON_KNOWLEDGE_FILES as readonly string[]).includes(filename);
+}
+
+// ---------------------------------------------------------------------------
+// Search manifest (build-time output)
+// ---------------------------------------------------------------------------
+
+/** Content type of a search chunk. */
+export type SearchChunkType = "page" | "knowledge" | "faq" | "prose";
+
+/** A single searchable content unit — one per block, knowledge entry, or FAQ entry. */
+export interface SearchChunk {
+  /** Deterministic ID: "{lang}:{urlPath}:{blockId}" or "{lang}:knowledge:{domain}" etc. */
+  id: string;
+  /** Full URL path to the page or resource (relative to site root). */
+  url: string;
+  /** ISO 639-1 language code (e.g. "de", "uk"). */
+  lang: string;
+  /** Content type — determines metadata filtering. */
+  type: SearchChunkType;
+  /** Block ID within the page (null for knowledge/faq chunks). */
+  blockId: string | null;
+  /** Heading text extracted from the block (optional). */
+  heading: string | null;
+  /** Body text extracted from the block, truncated to SEARCH_CHUNK_TEXT_MAX_LENGTH. */
+  text: string;
+}
+
+/** Static search manifest — build-time output written to public/api/agent/v1/search-manifest.json. */
+export interface SearchManifest {
+  schema: string;
+  site: string;
+  model: string;
+  dimensions: number;
+  /** sha256 hex over sorted-key JSON of this document minus contentHash + generatedAt. */
+  contentHash: string;
+  /** ISO timestamp — present in output but excluded from contentHash. */
+  generatedAt: string;
+  chunks: SearchChunk[];
+}
+
+// ---------------------------------------------------------------------------
+// Query / response (runtime API contracts)
+// ---------------------------------------------------------------------------
+
+/** Query parameters for the search endpoint. */
+export interface SearchQuery {
+  /** Natural language search query (max 1000 chars). */
+  q: string;
+  /** Filter by language (optional). */
+  lang?: string;
+  /** Filter by content type (optional). */
+  type?: SearchChunkType;
+  /** Number of results to return (default 5, max 20). */
+  topK?: number;
+}
+
+/** A single search result — chunk + similarity score. */
+export interface SearchResult {
+  chunk: SearchChunk;
+  /** Cosine similarity score (0..1, higher = more similar). */
+  score: number;
+}
+
+/** Response from the search endpoint. */
+export interface SearchResponse {
+  query: string;
+  results: SearchResult[];
+  /** Server-side processing time in milliseconds. */
+  tookMs: number;
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure: assemble + hash the search manifest. Deterministic — sorts chunks by id,
+ * excludes generatedAt from the content hash. Two runs on unchanged input are
+ * byte-identical (excluding the timestamp).
+ */
+export function buildSearchManifest(input: {
+  site: string;
+  model: string;
+  dimensions: number;
+  generatedAt: string;
+  chunks: SearchChunk[];
+}): SearchManifest {
+  const sortedChunks = [...input.chunks].sort((a, b) => a.id.localeCompare(b.id));
+  const base: Omit<SearchManifest, "contentHash"> = {
+    schema: SEARCH_MANIFEST_SCHEMA_VERSION,
+    site: input.site,
+    model: input.model,
+    dimensions: input.dimensions,
+    generatedAt: input.generatedAt,
+    chunks: sortedChunks,
+  };
+  const contentHash = computeSearchManifestContentHash(base);
+  return { ...base, contentHash };
+}
+
+/** sha256 hex over the canonical JSON of the manifest minus contentHash + generatedAt + proof. */
+export function computeSearchManifestContentHash(
+  doc: Omit<SearchManifest, "contentHash"> | Record<string, unknown>,
+): string {
+  return computeSignedContentHash(doc as Record<string, unknown>, ["generatedAt"]);
+}

package/src/share/env.d.ts

@@ -48,10 +48,6 @@ declare module "astro:env/server" {
   export const UPSTASH_QSTASH_NEXT_SIGNING_KEY: string | undefined;
   export const UPSTASH_REDIS_REST_URL: string | undefined;
   export const UPSTASH_REDIS_REST_TOKEN: string | undefined;
-  // Lagebild MVP: Supabase CRM buffer (self-enabling — adapter skips when absent).
-  export const SUPABASE_BUFFER_URL: string | undefined;
-  export const SUPABASE_BUFFER_SERVICE_KEY: string | undefined;
-  export const SUPABASE_BUFFER_TENANT_ID: string | undefined;
   // RFC-0191: Stripe billing — the webhook signing secret (stripe-webhook route) and the
   // server API key (billing client). Per-tenant; self-enabling — handlers fail-closed when absent.
   export const STRIPE_WEBHOOK_SECRET: string | undefined;

package/src/share/schemas/effects.ts

@@ -29,6 +29,7 @@ const NAMED_EFFECT_TARGETS = [
   "cta",
   "heading", // RFC-0151 — typographic effects on the section heading
   "subheading", // typographic effects on the section subheading/tagline
+  "background", // lighten overlay on the section background image
 ] as const;
 
 export const namedEffectTargetSchema = z.enum(NAMED_EFFECT_TARGETS);
@@ -106,12 +107,25 @@ export const tiltEffectSchema = z
   .strict();
 export type TiltEffect = z.infer<typeof tiltEffectSchema>;
 
+export const lightenEffectSchema = z
+  .object({
+    kind: z.literal("lighten"),
+    enabled: z.boolean(),
+    /** 0..1; opacity of the lightening overlay above the background image. */
+    opacity: z.number().min(0).max(1).optional(),
+    /** Color alias or raw value for the overlay. Defaults to --ds-color-bg. */
+    color: effectColorSchema.optional(),
+  })
+  .strict();
+export type LightenEffect = z.infer<typeof lightenEffectSchema>;
+
 export const effectSchema = z.discriminatedUnion("kind", [
   glassEffectSchema,
   shadowEffectSchema,
   glowEffectSchema,
   bulgeEffectSchema,
   tiltEffectSchema,
+  lightenEffectSchema,
 ]);
 export type Effect = z.infer<typeof effectSchema>;
 
@@ -128,6 +142,7 @@ export const EFFECT_KIND_META = {
   glow: { strategy: "text", maxPerStack: 1 },
   bulge: { strategy: "text", maxPerStack: 1 },
   tilt: { strategy: "text", maxPerStack: 1 },
+  lighten: { strategy: "surface", maxPerStack: 1 },
 } as const satisfies Record<EffectKind, { strategy: EffectRenderStrategy; maxPerStack: number }>;
 
 /**
@@ -138,6 +153,7 @@ export const EFFECT_KIND_META = {
 export const TARGET_ALLOWED_KINDS: Record<string, readonly EffectKind[]> = {
   heading: ["shadow", "glow", "bulge", "tilt"],
   subheading: ["shadow", "glow", "bulge", "tilt"],
+  background: ["lighten"],
 };
 
 const DEFAULT_ALLOWED_KINDS: readonly EffectKind[] = ["glass"];

package/src/share/schemas/media.ts

@@ -19,6 +19,7 @@
   <item>RFC-0525: added av1 field to VideoManifestSources for AV1 progressive delivery.</item>
   <item>RFC-0525: added opt-in av1 boolean to mediaSchema (default false) to skip slow AV1 encoding.</item>
   <item>RFC-0591: added maxSizeMb field to mediaSchema for two-pass bitrate-capped MP4 encoding.</item>
+  <item>RFC-0950: added fullscreen field to mediaSchema for content-controlled edge-to-edge layout.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -93,6 +94,9 @@ export const mediaSchema = z
     loop: z.boolean().optional(),
     muted: z.boolean().optional(),
     controls: z.boolean().optional(),
+
+    /** [RFC-0950] CSS edge-to-edge layout (hero-style), NOT the browser Fullscreen API. */
+    fullscreen: z.boolean().optional(),
     preload: z.enum(["none", "metadata", "auto"]).optional(),
 
     /** ambient/background only (RFC-0202): when the loop starts and what a tap does. */

package/src/share/schemas/section-shell.ts

@@ -13,6 +13,7 @@ module owns visual + structural wrapper props only.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+  <item>Added "flush" density for sections that need zero padding (e.g. fullscreen video flush to header).
 </CHANGE_SUMMARY>
 */
 
@@ -21,7 +22,7 @@ import { sectionBackgroundSchema } from "./section-background.ts";
 import { effectsSchema } from "./effects.ts";
 import { sectionMotionConfigSchema } from "./section-motion.ts";
 
-export const sectionDensitySchema = z.enum(["compact", "normal", "spacious"]);
+export const sectionDensitySchema = z.enum(["compact", "normal", "spacious", "flush"]);
 export type SectionDensity = z.infer<typeof sectionDensitySchema>;
 
 export const sectionToneSchema = z.enum(["default", "warning", "success", "muted"]);