@oxygen-agent/cli 1.1014.1465 → 1.1014.1597

package/node_modules/@oxygen/shared/dist/workspace-placement-bulk.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { CliHttpError } from "./cli-http-error.js";
+import { readWorkspacePlacementVariants, workspacePlacementId } from "./workspace-placement.js";
+export const MAX_BULK_PLACEMENT_MESSAGES = 20_000;
+export function bulkPlacementId(value) {
+    const h = createHash("sha256").update(value).digest("hex");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+export function readBulkPlacementProviders(value) {
+    if (value === undefined)
+        return ["google", "microsoft"];
+    if (!Array.isArray(value) || !value.length || value.length > 2 || new Set(value).size !== value.length || value.some(p => p !== "google" && p !== "microsoft"))
+        throw new CliHttpError(400, "invalid_request", "receiver_providers must select Google, Microsoft, or both.");
+    return [...value].sort();
+}
+/** Own-account rotation, never a sender × receiver Cartesian product. */
+export function buildWorkspacePlacementBulkPlan(input) {
+    if (!workspacePlacementId(input.requestId) || !workspacePlacementId(input.organizationId))
+        throw new CliHttpError(400, "workspace_test_invalid", "The deliverability test request is invalid.");
+    const requestId = input.requestId.toLowerCase(), organizationId = input.organizationId.toLowerCase();
+    const variants = readWorkspacePlacementVariants(input.variants), providers = readBulkPlacementProviders(input.receiverProviders);
+    const senders = [...input.senders].sort((a, b) => a.id.localeCompare(b.id));
+    if (!senders.length)
+        throw new CliHttpError(409, "workspace_test_no_eligible_senders", "No eligible sending mailboxes are available. Connect mailboxes with send permission or explicitly include paused mailboxes.", { details: { skipped_senders: input.skippedSenders?.slice(0, 20) ?? [], skipped_sender_count: input.skippedSenders?.length ?? 0 } });
+    const count = senders.length * variants.length * providers.length;
+    if (count > MAX_BULK_PLACEMENT_MESSAGES)
+        throw new CliHttpError(400, "workspace_test_bulk_limit", "This batch exceeds 20,000 messages. Choose fewer copy variants or receiving providers.");
+    const coverage = { google: { receivers: 0, planned: 0 }, microsoft: { receivers: 0, planned: 0 } };
+    const pools = new Map(providers.map(provider => {
+        const rows = [...input.receivers].filter(m => m.provider === provider).sort((a, b) => a.id.localeCompare(b.id));
+        coverage[provider].receivers = rows.length;
+        return [provider, rows];
+    }));
+    // Check coverage before rendering signatures/tracking. One sole own receiver
+    // cannot cover its own sender, even when that provider has a nonempty pool.
+    const missing = senders.flatMap(sender => providers.filter(p => !pools.get(p).some(r => r.id !== sender.id && r.address.toLowerCase() !== sender.address.toLowerCase())).map(provider => ({ sender: sender.address, provider })));
+    if (missing.length)
+        throw new CliHttpError(409, "workspace_test_receiver_coverage_missing", "Connected receiving mailboxes cannot cover every sender and requested provider without self-sends. Connect another receiving mailbox or change receiver_providers.", { details: { missing_coverage: missing.slice(0, 20), missing_coverage_count: missing.length, coverage } });
+    const probes = [];
+    let renderedBytes = 0;
+    for (const [senderIndex, sender] of senders.entries())
+        for (const [variantIndex, original] of variants.entries())
+            for (const provider of providers) {
+                const pool = pools.get(provider).filter(r => r.id !== sender.id && r.address.toLowerCase() !== sender.address.toLowerCase());
+                const receiver = pool[(senderIndex * variants.length + variantIndex) % pool.length];
+                const id = bulkPlacementId(`${organizationId}:${requestId}:${sender.id}:${receiver.id}:${original.key}`);
+                const variant = input.renderVariant ? input.renderVariant(original, sender, id) : original;
+                renderedBytes += Buffer.byteLength(JSON.stringify(variant));
+                if (renderedBytes > 32 * 1024 * 1024)
+                    throw new CliHttpError(400, "workspace_test_bulk_copy_limit", "Rendered copy exceeds the batch review limit. Shorten the copy or choose fewer variants.");
+                probes.push({ id, sender, receiver, variant });
+                coverage[provider].planned++;
+            }
+    const children = [];
+    for (let offset = 0; offset < probes.length; offset += 50) {
+        const child = { request_id: bulkPlacementId(`${organizationId}:${requestId}:child:${offset / 50}`), organization_id: organizationId, provider: "internal", billing_mode: "internal", credits: 0, allow_paused_probe: input.allowPausedProbe, receiver_scope: "workspace", rendered_at: input.renderedAt, rendering: input.rendering, probes: probes.slice(offset, offset + 50), excluded_self_sends: 0, message_count: Math.min(50, probes.length - offset) };
+        children.push({ ...child, plan_hash: createHash("sha256").update(JSON.stringify(child)).digest("hex") });
+    }
+    const plan = { request_id: requestId, organization_id: organizationId, rendered_at: input.renderedAt, message_count: count, child_count: children.length, sender_count: senders.length, receiver_providers: providers, skipped_senders: [...(input.skippedSenders ?? [])].sort((a, b) => a.id.localeCompare(b.id)), coverage, children };
+    return { ...plan, plan_hash: createHash("sha256").update(JSON.stringify(plan)).digest("hex") };
+}
+export function bulkPlacementSkippedPage(plan, cursor) {
+    if (cursor !== undefined && (typeof cursor !== "string" || !plan.skipped_senders.some(s => s.id === cursor)))
+        throw new CliHttpError(400, "workspace_test_page_invalid", "Use the skipped-sender cursor from this deliverability test.");
+    const start = cursor === undefined ? 0 : plan.skipped_senders.findIndex(s => s.id === cursor) + 1;
+    const skipped = plan.skipped_senders.slice(start, start + 20), more = start + skipped.length < plan.skipped_senders.length;
+    return { skipped_senders: skipped, skipped_sender_count: plan.skipped_senders.length, skipped_has_more: more, next_skipped_cursor: more ? skipped.at(-1).id : null };
+}

package/node_modules/@oxygen/shared/dist/workspace-placement-view.d.ts

@@ -123,7 +123,8 @@ export declare function workspacePlacementPreviewPage(plan: WorkspacePlacementPl
     billing_mode: "internal";
     credits: 0;
     allow_paused_probe: boolean;
-    receiver_scope?: "workspace" | "network";
+    receiver_scope?: "workspace" | "network" | "staff";
+    staff?: import("./workspace-placement.js").StaffPlacementGrant;
     rendered_at?: string;
     rendering?: {
         tracking_opens: boolean;

package/node_modules/@oxygen/shared/dist/workspace-placement.d.ts

@@ -13,6 +13,13 @@ export type WorkspacePlacementMailbox = {
     signature_html: string | null;
     organization_id?: string;
     network_id?: string;
+    environment?: "dev" | "prod";
+};
+export type StaffPlacementGrant = {
+    actor_id: string;
+    source_environment: "dev" | "prod";
+    receiver_environment: "dev" | "prod";
+    receiver_workspace_id: string;
 };
 export type WorkspacePlacementProbe = {
     id: string;
@@ -27,7 +34,8 @@ export type WorkspacePlacementPlan = {
     billing_mode: "internal";
     credits: 0;
     allow_paused_probe: boolean;
-    receiver_scope?: "workspace" | "network";
+    receiver_scope?: "workspace" | "network" | "staff";
+    staff?: StaffPlacementGrant;
     rendered_at?: string;
     rendering?: {
         tracking_opens: boolean;
@@ -42,6 +50,7 @@ export type WorkspacePlacementPlan = {
 export declare function workspacePlacementId(value: unknown): value is string;
 export declare function readWorkspacePlacementVariants(value: unknown): WorkspacePlacementVariant[];
 export declare function readWorkspacePlacementMailboxIds(value: unknown): string[];
+export declare function workspacePlacementPlanHash(plan: Omit<WorkspacePlacementPlan, "plan_hash">): string;
 export declare function buildWorkspacePlacementPlan(input: {
     requestId: string;
     organizationId: string;
@@ -52,6 +61,7 @@ export declare function buildWorkspacePlacementPlan(input: {
     renderedAt?: string;
     rendering?: WorkspacePlacementPlan["rendering"];
     network?: boolean;
+    staff?: StaffPlacementGrant;
     renderVariant?: (variant: WorkspacePlacementVariant, sender: WorkspacePlacementMailbox, probeId: string) => WorkspacePlacementVariant;
 }): WorkspacePlacementPlan;
 export type WorkspacePlacementObservation = {

package/node_modules/@oxygen/shared/dist/workspace-placement.js

@@ -38,6 +38,16 @@ function probeId(value) {
     const h = createHash("sha256").update(value).digest("hex");
     return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
 }
+function canonicalPlacementValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalPlacementValue);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, canonicalPlacementValue(item)]));
+    return value;
+}
+export function workspacePlacementPlanHash(plan) {
+    return createHash("sha256").update(JSON.stringify(plan.receiver_scope === "staff" ? canonicalPlacementValue(plan) : plan)).digest("hex");
+}
 export function buildWorkspacePlacementPlan(input) {
     if (!workspacePlacementId(input.requestId) || !workspacePlacementId(input.organizationId))
         invalid("The workspace test request is invalid.");
@@ -46,7 +56,8 @@ export function buildWorkspacePlacementPlan(input) {
     const variants = readWorkspacePlacementVariants(input.variants);
     const senders = [...input.senders].sort((a, b) => a.id.localeCompare(b.id));
     const receivers = [...input.receivers].sort((a, b) => a.id.localeCompare(b.id));
-    const self = (sender, receiver) => sender.id === receiver.id || sender.address.toLowerCase() === receiver.address.toLowerCase();
+    const identity = (box) => `${box.environment ?? input.staff?.source_environment ?? ""}:${box.organization_id ?? organizationId}:${box.id}`;
+    const self = (sender, receiver) => identity(sender) === identity(receiver) || sender.address.toLowerCase() === receiver.address.toLowerCase();
     let excluded = 0, pairs = 0;
     for (const sender of senders)
         for (const receiver of receivers) {
@@ -72,7 +83,7 @@ export function buildWorkspacePlacementPlan(input) {
                     if (group[sequence % group.length].id !== receiver.id)
                         continue;
                 }
-                const id = probeId(`${organizationId}:${requestId}:${sender.id}:${receiver.id}:${original.key}`);
+                const id = probeId(input.staff ? `${organizationId}:${requestId}:${identity(sender)}:${identity(receiver)}:${original.key}` : `${organizationId}:${requestId}:${sender.id}:${receiver.id}:${original.key}`);
                 const variant = input.renderVariant ? input.renderVariant(original, sender, id) : original;
                 probes.push({ id, sender, receiver, variant });
             }
@@ -81,10 +92,10 @@ export function buildWorkspacePlacementPlan(input) {
     if (!probes.length || probes.length > 50)
         invalid("A workspace test must send between one and 50 messages after excluding self-sends.");
     const plan = { request_id: requestId, organization_id: organizationId, provider: "internal",
-        ...(input.network ? { receiver_scope: "network" } : {}), billing_mode: "internal", credits: 0, allow_paused_probe: input.allowPausedProbe,
+        ...(input.network ? { receiver_scope: "network" } : input.staff ? { receiver_scope: "staff", staff: input.staff } : {}), billing_mode: "internal", credits: 0, allow_paused_probe: input.allowPausedProbe,
         ...(input.renderedAt ? { rendered_at: input.renderedAt } : {}), ...(input.rendering ? { rendering: input.rendering } : {}),
         probes, excluded_self_sends: excluded, message_count: probes.length };
-    return { ...plan, plan_hash: createHash("sha256").update(JSON.stringify(plan)).digest("hex") };
+    return { ...plan, plan_hash: workspacePlacementPlanHash(plan) };
 }
 export function googleWorkspacePlacement(labels, messageId, observedAt) {
     const categories = ["PERSONAL", "PROMOTIONS", "SOCIAL", "UPDATES", "FORUMS"].filter(k => labels.includes(`CATEGORY_${k}`));

package/node_modules/@oxygen/shared/dist/write-rollout.d.ts

@@ -0,0 +1,11 @@
+/** Writes become compatible only after every consuming role has adopted the new source. */
+export declare function casePreservingTagWritesReady(env?: NodeJS.ProcessEnv): boolean;
+export declare function campaignMetadataWritesReady(env?: NodeJS.ProcessEnv): boolean;
+export declare function assertCampaignMetadataWritesReady(field: string, env?: NodeJS.ProcessEnv): void;
+export declare function mailboxStandbyWritesReady(env?: NodeJS.ProcessEnv): boolean;
+export declare function assertMailboxStandbyWritesReady(): void;
+export declare function assertMailboxStandbyMetadataWritesReady(metadata: Record<string, unknown> | null | undefined): void;
+export declare function staffPlacementWritesReady(env?: NodeJS.ProcessEnv): boolean;
+export declare function assertStaffPlacementWritesReady(env?: NodeJS.ProcessEnv): void;
+export declare function assertPublishingApprovalPolicyWriteReady(policy: unknown): void;
+export declare function assertSequenceMetadataWritesReady(definition: unknown): void;

package/node_modules/@oxygen/shared/dist/write-rollout.js

@@ -0,0 +1,59 @@
+import { OxygenError } from "./cli-result.js";
+import { isProductionData } from "./deploy-env.js";
+/** Writes become compatible only after every consuming role has adopted the new source. */
+export function casePreservingTagWritesReady(env = process.env) {
+    return !isProductionData(env) || env.OXYGEN_CASE_PRESERVING_TAG_WRITES_READY === "1";
+}
+export function campaignMetadataWritesReady(env = process.env) {
+    return !isProductionData(env) || env.OXYGEN_CAMPAIGN_METADATA_WRITES_READY === "1";
+}
+export function assertCampaignMetadataWritesReady(field, env = process.env) {
+    if (campaignMetadataWritesReady(env))
+        return;
+    throw new OxygenError("feature_rollout_pending", "This setting is not available yet.", {
+        details: { field, next_step: "Try again after the workspace update is available." }, exitCode: 1,
+    });
+}
+export function mailboxStandbyWritesReady(env = process.env) {
+    return campaignMetadataWritesReady(env)
+        && (!isProductionData(env) || env.OXYGEN_MAILBOX_STANDBY_WRITES_READY === "1");
+}
+export function assertMailboxStandbyWritesReady() {
+    if (mailboxStandbyWritesReady())
+        return;
+    throw new OxygenError("feature_rollout_pending", "Mailbox standby is not available yet.", {
+        details: { field: "mailbox_standby", next_step: "Try again after the workspace update is available." }, exitCode: 1,
+    });
+}
+export function assertMailboxStandbyMetadataWritesReady(metadata) {
+    if (Object.hasOwn(metadata ?? {}, "outreach_role") || Object.hasOwn(metadata ?? {}, "standby_promotion")) {
+        assertMailboxStandbyWritesReady();
+    }
+}
+export function staffPlacementWritesReady(env = process.env) {
+    return !isProductionData(env) || env.OXYGEN_STAFF_PLACEMENT_WRITES_READY === "1";
+}
+export function assertStaffPlacementWritesReady(env = process.env) {
+    if (staffPlacementWritesReady(env))
+        return;
+    throw new OxygenError("feature_rollout_pending", "Staff placement tests are not available yet.", {
+        details: { field: "staff_placement", next_step: "Try again after the workspace update is available." }, exitCode: 1,
+    });
+}
+export function assertPublishingApprovalPolicyWriteReady(policy) {
+    if (policy && typeof policy === "object" && "mode" in policy && policy.mode === "owner") {
+        assertCampaignMetadataWritesReady("publishing_approval");
+    }
+}
+export function assertSequenceMetadataWritesReady(definition) {
+    if (!definition || typeof definition !== "object" || !("steps" in definition) || !Array.isArray(definition.steps))
+        return;
+    for (const step of definition.steps) {
+        if (!step || typeof step !== "object")
+            continue;
+        if (step.kind === "wait" && step.working_days === true)
+            assertCampaignMetadataWritesReady("working_days");
+        if (step.kind === "wait_for_connection" && step.withdraw_on_timeout === true)
+            assertCampaignMetadataWritesReady("withdraw_on_timeout");
+    }
+}

package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.d.ts

@@ -150,7 +150,7 @@ export declare const workflowCodeV1Schema: {
 export declare const workflowGraphManifestSchema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly title: "OXYGEN Workflow Graph Manifest (oxygen-workflows-v2)";
-    readonly description: "A node + edge workflow graph. Exactly one trigger node; every node reachable from it; cycles are illegal except a single back-edge from inside a loop's body to that loop node.";
+    readonly description: string;
     readonly type: "object";
     readonly additionalProperties: true;
     readonly properties: {
@@ -923,6 +923,93 @@ export declare const workflowGraphManifestSchema: {
         };
     };
     readonly required: readonly ["manifest_version", "workflow", "nodes", "edges", "source_hash", "compiler_version"];
+    readonly examples: readonly [{
+        readonly manifest_version: 2;
+        readonly compiler_version: "oxygen-workflows-v2";
+        readonly workflow: {
+            readonly id: "form-signups";
+            readonly name: "Form signups";
+            readonly status: "disabled";
+        };
+        readonly trigger: {
+            readonly type: "webhook";
+            readonly trigger_id: "form-signup";
+            readonly status: "disabled";
+            readonly secret_required: true;
+        };
+        readonly input_schema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly email: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["name", "email"];
+        };
+        readonly nodes: readonly [{
+            readonly id: "trigger";
+            readonly name: "Form signup";
+            readonly kind: "trigger";
+            readonly ui: {
+                readonly x: 0;
+                readonly y: 0;
+            };
+        }, {
+            readonly id: "row";
+            readonly name: "Map row";
+            readonly kind: "set";
+            readonly ui: {
+                readonly x: 240;
+                readonly y: 0;
+            };
+            readonly fields: readonly [{
+                readonly key: "name";
+                readonly value: {
+                    readonly type: "ref";
+                    readonly path: "trigger.input.name";
+                };
+            }, {
+                readonly key: "email";
+                readonly value: {
+                    readonly type: "ref";
+                    readonly path: "trigger.input.email";
+                };
+            }];
+        }, {
+            readonly id: "add_row";
+            readonly name: "Add row";
+            readonly kind: "tool";
+            readonly ui: {
+                readonly x: 480;
+                readonly y: 0;
+            };
+            readonly tool: "oxygen_table_rows_insert";
+            readonly effect: "external_write";
+            readonly params: {
+                readonly table: {
+                    readonly type: "literal";
+                    readonly value: "signups";
+                };
+                readonly values: {
+                    readonly type: "ref";
+                    readonly path: "steps.row.output";
+                };
+            };
+        }];
+        readonly edges: readonly [{
+            readonly id: "trigger-row";
+            readonly source: "trigger";
+            readonly target: "row";
+        }, {
+            readonly id: "row-add_row";
+            readonly source: "row";
+            readonly target: "add_row";
+        }];
+        readonly source_hash: "draft";
+    }];
 };
 export declare const portableWorkflowDefinitionSchema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
@@ -940,7 +1027,7 @@ export declare const portableWorkflowDefinitionSchema: {
         readonly graph: {
             readonly $schema: "https://json-schema.org/draft/2020-12/schema";
             readonly title: "OXYGEN Workflow Graph Manifest (oxygen-workflows-v2)";
-            readonly description: "A node + edge workflow graph. Exactly one trigger node; every node reachable from it; cycles are illegal except a single back-edge from inside a loop's body to that loop node.";
+            readonly description: string;
             readonly type: "object";
             readonly additionalProperties: true;
             readonly properties: {
@@ -1713,6 +1800,93 @@ export declare const portableWorkflowDefinitionSchema: {
                 };
             };
             readonly required: readonly ["manifest_version", "workflow", "nodes", "edges", "source_hash", "compiler_version"];
+            readonly examples: readonly [{
+                readonly manifest_version: 2;
+                readonly compiler_version: "oxygen-workflows-v2";
+                readonly workflow: {
+                    readonly id: "form-signups";
+                    readonly name: "Form signups";
+                    readonly status: "disabled";
+                };
+                readonly trigger: {
+                    readonly type: "webhook";
+                    readonly trigger_id: "form-signup";
+                    readonly status: "disabled";
+                    readonly secret_required: true;
+                };
+                readonly input_schema: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                        readonly email: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["name", "email"];
+                };
+                readonly nodes: readonly [{
+                    readonly id: "trigger";
+                    readonly name: "Form signup";
+                    readonly kind: "trigger";
+                    readonly ui: {
+                        readonly x: 0;
+                        readonly y: 0;
+                    };
+                }, {
+                    readonly id: "row";
+                    readonly name: "Map row";
+                    readonly kind: "set";
+                    readonly ui: {
+                        readonly x: 240;
+                        readonly y: 0;
+                    };
+                    readonly fields: readonly [{
+                        readonly key: "name";
+                        readonly value: {
+                            readonly type: "ref";
+                            readonly path: "trigger.input.name";
+                        };
+                    }, {
+                        readonly key: "email";
+                        readonly value: {
+                            readonly type: "ref";
+                            readonly path: "trigger.input.email";
+                        };
+                    }];
+                }, {
+                    readonly id: "add_row";
+                    readonly name: "Add row";
+                    readonly kind: "tool";
+                    readonly ui: {
+                        readonly x: 480;
+                        readonly y: 0;
+                    };
+                    readonly tool: "oxygen_table_rows_insert";
+                    readonly effect: "external_write";
+                    readonly params: {
+                        readonly table: {
+                            readonly type: "literal";
+                            readonly value: "signups";
+                        };
+                        readonly values: {
+                            readonly type: "ref";
+                            readonly path: "steps.row.output";
+                        };
+                    };
+                }];
+                readonly edges: readonly [{
+                    readonly id: "trigger-row";
+                    readonly source: "trigger";
+                    readonly target: "row";
+                }, {
+                    readonly id: "row-add_row";
+                    readonly source: "row";
+                    readonly target: "add_row";
+                }];
+                readonly source_hash: "draft";
+            }];
         };
         readonly requirements: {
             readonly type: "object";

package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.js

@@ -300,10 +300,58 @@ const edgeSchema = {
     },
     required: ["id", "source", "target"],
 };
+// The smallest graph that lints clean in both phases and runs: a webhook adds
+// one Table row. Agents that guessed the envelope burned their turn on lint
+// round trips (status, source_hash, ui, edge ids, effect, bindings) or never
+// found the row-insert tool at all (System 1 sweep 2, 2026-10-20). Pinned by a
+// lint test so it cannot drift from what the linter accepts.
+const minimalGraphManifestExample = {
+    manifest_version: WORKFLOW_GRAPH_MANIFEST_VERSION,
+    compiler_version: WORKFLOW_GRAPH_COMPILER_VERSION,
+    workflow: { id: "form-signups", name: "Form signups", status: "disabled" },
+    trigger: { type: "webhook", trigger_id: "form-signup", status: "disabled", secret_required: true },
+    input_schema: {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+    },
+    nodes: [
+        { id: "trigger", name: "Form signup", kind: "trigger", ui: { x: 0, y: 0 } },
+        {
+            id: "row",
+            name: "Map row",
+            kind: "set",
+            ui: { x: 240, y: 0 },
+            fields: [
+                { key: "name", value: { type: "ref", path: "trigger.input.name" } },
+                { key: "email", value: { type: "ref", path: "trigger.input.email" } },
+            ],
+        },
+        {
+            id: "add_row",
+            name: "Add row",
+            kind: "tool",
+            ui: { x: 480, y: 0 },
+            tool: "oxygen_table_rows_insert",
+            effect: "external_write",
+            params: {
+                table: { type: "literal", value: "signups" },
+                values: { type: "ref", path: "steps.row.output" },
+            },
+        },
+    ],
+    edges: [
+        { id: "trigger-row", source: "trigger", target: "row" },
+        { id: "row-add_row", source: "row", target: "add_row" },
+    ],
+    source_hash: "draft",
+};
 export const workflowGraphManifestSchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     title: "OXYGEN Workflow Graph Manifest (oxygen-workflows-v2)",
-    description: "A node + edge workflow graph. Exactly one trigger node; every node reachable from it; cycles are illegal except a single back-edge from inside a loop's body to that loop node.",
+    description: "A node + edge workflow graph. Exactly one trigger node; every node reachable from it; cycles are illegal except a single back-edge from inside a loop's body to that loop node."
+        + " `examples[0]` is a minimal valid graph: a webhook trigger (type api is the by-hand trigger) whose payload a set node maps, and a tool node adding the row with oxygen_table_rows_insert (table slug or id; effect external_write)."
+        + " source_hash must be a non-empty string; lint does not verify it.",
     type: "object",
     additionalProperties: true,
     properties: {
@@ -328,6 +376,7 @@ export const workflowGraphManifestSchema = {
         created_at: { type: "string" },
     },
     required: ["manifest_version", "workflow", "nodes", "edges", "source_hash", "compiler_version"],
+    examples: [minimalGraphManifestExample],
 };
 export const portableWorkflowDefinitionSchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",