feat: prepare embeddable council payload (#2)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Victor-David-Medina

packages/formations/README.md

@@ -29,6 +29,21 @@ const synthesisPrompt = buildSynthesisPrompt(strategyRoom, 'What should we do ne
 ]);
 ```
 
+## Embeddable Payload
+
+Use the minimal embed API when you want a website, docs page, or product surface to render a CouncilVerse debate shell without binding to any specific LLM provider.
+
+```bash
+node --input-type=module -e "import { buildCouncilEmbedPayload } from '@relaylaunch/councilverse-formations'; console.log(JSON.stringify(buildCouncilEmbedPayload('technical-review', 'Should we ship the embeddable verdict widget?'), null, 2));"
+```
+
+The payload includes:
+
+- `schemaVersion: "councilverse.embed.v1"`
+- formation metadata and default round count
+- one provider-agnostic system prompt per role
+- a synthesis prompt ready for your own model gateway
+
 ## Formations
 
 | ID | Name | Methodology |

packages/formations/__tests__/embed.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { buildCouncilEmbedPayload } from "../src";
+
+describe("CouncilVerse embeddable payload", () => {
+  it("builds a provider-agnostic embed payload for a formation", () => {
+    const payload = buildCouncilEmbedPayload(
+      "technical-review",
+      "Should we expose CouncilVerse as an embeddable verdict widget?",
+    );
+
+    expect(payload.schemaVersion).toBe("councilverse.embed.v1");
+    expect(payload.formationId).toBe("technical-review");
+    expect(payload.agents).toHaveLength(5);
+    expect(payload.defaultRounds).toBe(2);
+    expect(payload.synthesisPrompt).toContain("Should we expose CouncilVerse");
+  });
+
+  it("includes one system prompt per role without requiring an LLM provider key", () => {
+    const payload = buildCouncilEmbedPayload("strategy-room", "Pick the next release wedge.");
+
+    expect(payload.agents.map((agent) => agent.title)).toEqual([
+      "Observer",
+      "Orienter",
+      "Strategist",
+      "Executor",
+      "Red Cell",
+    ]);
+    expect(payload.agents[0].systemPrompt).toContain("You are the Observer");
+    expect(JSON.stringify(payload)).not.toContain("API_KEY");
+  });
+
+  it("trims the public question and rejects empty embed requests", () => {
+    expect(buildCouncilEmbedPayload("risk-council", "  What can break launch?  ").question)
+      .toBe("What can break launch?");
+    expect(() => buildCouncilEmbedPayload("risk-council", "   ")).toThrow("question is required");
+  });
+});

packages/formations/src/index.ts

@@ -308,6 +308,24 @@ export function getFormationsByMethodology(methodology: string): Formation[] {
   );
 }
 
+export interface CouncilEmbedAgent {
+  id: string;
+  title: string;
+  perspective: string;
+  systemPrompt: string;
+}
+
+export interface CouncilEmbedPayload {
+  schemaVersion: "councilverse.embed.v1";
+  formationId: FormationId;
+  formationName: string;
+  methodology: string;
+  question: string;
+  defaultRounds: number;
+  agents: CouncilEmbedAgent[];
+  synthesisPrompt: string;
+}
+
 const ANTI_SYCOPHANCY_RULES = [
   "6. NEVER use hollow agreement phrases: 'I agree', 'exactly right', 'great point', 'well said', 'as you mentioned'",
   "7. If you change your position between rounds, you MUST state what new evidence caused the change",
@@ -333,6 +351,33 @@ export function buildSystemPrompt(formation: Formation, roleIndex: number): stri
   ].join("\n");
 }
 
+export function buildCouncilEmbedPayload(
+  formationId: FormationId,
+  question: string,
+): CouncilEmbedPayload {
+  const trimmedQuestion = question.trim();
+  if (!trimmedQuestion) {
+    throw new Error("Embed question is required.");
+  }
+
+  const formation = getFormation(formationId);
+  return {
+    schemaVersion: "councilverse.embed.v1",
+    formationId: formation.id,
+    formationName: formation.name,
+    methodology: formation.methodology,
+    question: trimmedQuestion,
+    defaultRounds: formation.defaultRounds,
+    agents: formation.roles.map((role, index) => ({
+      id: `${formation.id}-agent-${index + 1}`,
+      title: role.title,
+      perspective: role.perspective,
+      systemPrompt: buildSystemPrompt(formation, index),
+    })),
+    synthesisPrompt: buildSynthesisPrompt(formation, trimmedQuestion, []),
+  };
+}
+
 export interface FlipRateEntry {
   agentId: string;
   round: number;