pomerado 0.1.0 → 0.1.1

package/dist/typescript/authoring/core/SKILL.md

@@ -140,6 +140,18 @@ request and the flow, never from one caller's account or example.
   schema, inside `Schema.optional(...)` for an optional one; a `Schema.Date` keeps it only on
   `Schema.optional(Schema.Date)` or `Schema.propertySignature(Schema.Date)`. Callers see each
   beside its name.
+- Shape inputs and outputs like Pomerado's own API, so every tool reads alike: field names in
+  snake_case; dates as `YYYY-MM-DD` and timestamps as ISO 8601 with an offset; money as an
+  integer in minor units with an ISO 4217 `currency` beside it, such as `total_minor` 12999 and
+  `currency` `"USD"`; enum values in lowercase snake_case (`"premium_economy"`); booleans named
+  as statements (`refundable`, not `is_refundable_flag`); lists named in the plural; and the
+  unit in the field name or its description (`duration_minutes`). Convert between these and the
+  site's own formats in code.
+- Give every input field one `examples` annotation value, which callers, the docs and the Try it
+  form use to assemble a sample request: public, generic data such as a well-known airport code
+  (`examples: ["SFO"]`), a date a few weeks ahead or a common product category. Never use a value
+  from this session: not the caller's input, the owner's answers or anything the site showed
+  this account.
 - Descriptions, titles, examples and defaults are published and reviewed for private data,
   and an annotation never declares its contents public. Explain constraints without copying private input
   or unneeded numeric identifiers; for a nonnegative safe integer,

package/dist/typescript/authoring/examples/dates-and-dropdowns.js

@@ -20,8 +20,11 @@ const failures = [
 export default defineOperation({
     name: "set_departure",
     input: Schema.Struct({
-        date: DateOnly.annotations({ description: "Departure date, YYYY-MM-DD" }),
-        cabin: Cabin.annotations({ description: "Cabin class to search" }),
+        date: DateOnly.annotations({
+            description: "Departure date, YYYY-MM-DD",
+            examples: ["2026-11-14"],
+        }),
+        cabin: Cabin.annotations({ description: "Cabin class to search", examples: ["economy"] }),
     }),
     output: Schema.Struct({
         date: DateOnly.annotations({ description: "Departure date the form now holds, YYYY-MM-DD" }),

package/dist/typescript/authoring/examples/dates-and-dropdowns.ts

@@ -23,8 +23,11 @@ export default defineOperation(
   {
     name: "set_departure",
     input: Schema.Struct({
-      date: DateOnly.annotations({ description: "Departure date, YYYY-MM-DD" }),
-      cabin: Cabin.annotations({ description: "Cabin class to search" }),
+      date: DateOnly.annotations({
+        description: "Departure date, YYYY-MM-DD",
+        examples: ["2026-11-14"],
+      }),
+      cabin: Cabin.annotations({ description: "Cabin class to search", examples: ["economy"] }),
     }),
     output: Schema.Struct({
       date: DateOnly.annotations({ description: "Departure date the form now holds, YYYY-MM-DD" }),

package/dist/typescript/authoring/examples/dates-and-files.d.ts

@@ -9,11 +9,11 @@ export declare const pickTravelDate: import("../../src/runtime/kernel-operation.
 }>;
 declare const _default: import("../../src/runtime/kernel-operation.js").KernelOperation<{
     readonly name: string;
-    readonly mimeType: string;
-    readonly contentBase64: string;
+    readonly mime_type: string;
+    readonly content_base64: string;
 }, {
-    readonly contentBase64: string;
-    readonly mimeType: string;
+    readonly content_base64: string;
+    readonly mime_type: string;
     readonly name: string;
 }, {
     readonly name: string;

package/dist/typescript/authoring/examples/dates-and-files.js

@@ -59,10 +59,10 @@ export default defineOperation({
         name: Schema.NonEmptyString.annotations({
             description: "File name for the document, with its extension",
         }),
-        mimeType: Schema.NonEmptyString.annotations({
+        mime_type: Schema.NonEmptyString.annotations({
             description: "The document's media type, such as application/pdf",
         }),
-        contentBase64: Schema.String.annotations({ description: "The document's bytes, base64" }),
+        content_base64: Schema.String.annotations({ description: "The document's bytes, base64" }),
     }),
     output: Schema.Struct({
         name: Schema.String.annotations({ description: "Name of the file the field now holds" }),
@@ -79,8 +79,8 @@ export default defineOperation({
         await field.setInputFiles(
           {
             name: ${JSON.stringify(input.name)},
-            mimeType: ${JSON.stringify(input.mimeType)},
-            buffer: Buffer.from(${JSON.stringify(input.contentBase64)}, "base64"),
+            mimeType: ${JSON.stringify(input.mime_type)},
+            buffer: Buffer.from(${JSON.stringify(input.content_base64)}, "base64"),
           },
           { timeout: 30000 },
         );
@@ -95,7 +95,7 @@ export default defineOperation({
     if ("failure" in result)
         throw new errors.OperationFailure(result.failure, { dispatch: "not_sent" });
     const file = result.files[0];
-    const size = Buffer.from(input.contentBase64, "base64").byteLength;
+    const size = Buffer.from(input.content_base64, "base64").byteLength;
     // Selection is not proof the site accepted the upload; this reads back only the choice.
     if (result.files.length !== 1 || file?.name !== input.name || file.size !== size)
         throw new errors.OperationFailure("The chosen file did not read back", { dispatch: "sent" });

package/dist/typescript/authoring/examples/dates-and-files.ts

@@ -76,10 +76,10 @@ export default defineOperation(
       name: Schema.NonEmptyString.annotations({
         description: "File name for the document, with its extension",
       }),
-      mimeType: Schema.NonEmptyString.annotations({
+      mime_type: Schema.NonEmptyString.annotations({
         description: "The document's media type, such as application/pdf",
       }),
-      contentBase64: Schema.String.annotations({ description: "The document's bytes, base64" }),
+      content_base64: Schema.String.annotations({ description: "The document's bytes, base64" }),
     }),
     output: Schema.Struct({
       name: Schema.String.annotations({ description: "Name of the file the field now holds" }),
@@ -97,8 +97,8 @@ export default defineOperation(
         await field.setInputFiles(
           {
             name: ${JSON.stringify(input.name)},
-            mimeType: ${JSON.stringify(input.mimeType)},
-            buffer: Buffer.from(${JSON.stringify(input.contentBase64)}, "base64"),
+            mimeType: ${JSON.stringify(input.mime_type)},
+            buffer: Buffer.from(${JSON.stringify(input.content_base64)}, "base64"),
           },
           { timeout: 30000 },
         );
@@ -118,7 +118,7 @@ export default defineOperation(
     if ("failure" in result)
       throw new errors.OperationFailure(result.failure, { dispatch: "not_sent" });
     const file = result.files[0];
-    const size = Buffer.from(input.contentBase64, "base64").byteLength;
+    const size = Buffer.from(input.content_base64, "base64").byteLength;
     // Selection is not proof the site accepted the upload; this reads back only the choice.
     if (result.files.length !== 1 || file?.name !== input.name || file.size !== size)
       throw new errors.OperationFailure("The chosen file did not read back", { dispatch: "sent" });

package/dist/typescript/authoring/examples/dialog-picker.d.ts

@@ -5,8 +5,8 @@ declare const _default: import("../../src/runtime/kernel-operation.js").KernelOp
     readonly key: string;
     readonly query: string;
 }, {
-    readonly selectedKey: string;
+    readonly selected_key: string;
 }, {
-    readonly selectedKey: string;
+    readonly selected_key: string;
 }>;
 export default _default;

package/dist/typescript/authoring/examples/dialog-picker.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 import { defineOperation } from "../../src/browser/index.js";
-const Picked = Schema.Union(Schema.Struct({ selectedKey: Schema.NonEmptyString }), Schema.Struct({
+const Picked = Schema.Union(Schema.Struct({ selected_key: Schema.NonEmptyString }), Schema.Struct({
     failure: Schema.Literal("query_mismatch", "option_identity_mismatch", "committed_key_mismatch"),
 }));
 // These roles, names and data attributes describe one synthetic site's observed picker.
@@ -14,7 +14,7 @@ export default defineOperation({
         }),
     }),
     output: Schema.Struct({
-        selectedKey: Schema.NonEmptyString.annotations({
+        selected_key: Schema.NonEmptyString.annotations({
             description: "Catalog key the page now shows as selected",
         }),
     }),
@@ -45,7 +45,7 @@ export default defineOperation({
         const committed = page.getByRole("textbox", { name: "Selected catalog key", exact: true });
         const until = Date.now() + 30000;
         while (Date.now() < until) {
-          if ((await committed.inputValue({ timeout: 1000 })) === key) return { selectedKey: key };
+          if ((await committed.inputValue({ timeout: 1000 })) === key) return { selected_key: key };
           await page.waitForTimeout(100);
         }
         return { failure: "committed_key_mismatch" };

package/dist/typescript/authoring/examples/dialog-picker.ts

@@ -2,7 +2,7 @@ import { Schema } from "effect";
 import { defineOperation } from "../../src/browser/index.js";
 
 const Picked = Schema.Union(
-  Schema.Struct({ selectedKey: Schema.NonEmptyString }),
+  Schema.Struct({ selected_key: Schema.NonEmptyString }),
   Schema.Struct({
     failure: Schema.Literal("query_mismatch", "option_identity_mismatch", "committed_key_mismatch"),
   }),
@@ -20,7 +20,7 @@ export default defineOperation(
       }),
     }),
     output: Schema.Struct({
-      selectedKey: Schema.NonEmptyString.annotations({
+      selected_key: Schema.NonEmptyString.annotations({
         description: "Catalog key the page now shows as selected",
       }),
     }),
@@ -52,7 +52,7 @@ export default defineOperation(
         const committed = page.getByRole("textbox", { name: "Selected catalog key", exact: true });
         const until = Date.now() + 30000;
         while (Date.now() < until) {
-          if ((await committed.inputValue({ timeout: 1000 })) === key) return { selectedKey: key };
+          if ((await committed.inputValue({ timeout: 1000 })) === key) return { selected_key: key };
           await page.waitForTimeout(100);
         }
         return { failure: "committed_key_mismatch" };

package/dist/typescript/authoring/examples/native-dialog.d.ts

@@ -1,7 +1,7 @@
 declare const _default: import("../../src/runtime/kernel-operation.js").KernelOperation<{
-    readonly invoiceId: string;
+    readonly invoice_id: string;
 }, {
-    readonly invoiceId: string;
+    readonly invoice_id: string;
 }, {
     readonly deleted: boolean;
 }, {

package/dist/typescript/authoring/examples/native-dialog.js

@@ -7,7 +7,7 @@ const InvoiceId = Schema.String.pipe(Schema.pattern(/^[A-Za-z0-9_-]{1,100}$/));
 export default defineOperation({
     name: "delete_invoice",
     input: Schema.Struct({
-        invoiceId: InvoiceId.annotations({ description: "ID of the invoice to delete" }),
+        invoice_id: InvoiceId.annotations({ description: "ID of the invoice to delete" }),
     }),
     output: Schema.Struct({
         deleted: Schema.Boolean.annotations({
@@ -18,7 +18,7 @@ export default defineOperation({
     const raised = await kernel.browsers.playwright.execute(sessionId, {
         timeout_sec: 30,
         code: `
-        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoiceId)}, { exact: true }) });
+        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoice_id)}, { exact: true }) });
         if ((await row.count()) !== 1) return { failure: "invoice_missing" };
         const shown = new Promise((resolve) => page.once("dialog", (dialog) => {
           globalThis.dialog = dialog;
@@ -53,7 +53,7 @@ export default defineOperation({
             ? `await globalThis.dialog.accept(${JSON.stringify(decision.promptText ?? "")});`
             : "await globalThis.dialog.dismiss();"}
         delete globalThis.dialog;
-        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoiceId)}, { exact: true }) });
+        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoice_id)}, { exact: true }) });
         // Read the result back: the row is gone only if the site deleted it.
         await row.waitFor({ state: ${JSON.stringify(decision.choice === "accept" ? "detached" : "visible")}, timeout: 10000 });
         return { deleted: (await row.count()) === 0 };

package/dist/typescript/authoring/examples/native-dialog.ts

@@ -10,7 +10,7 @@ export default defineOperation(
   {
     name: "delete_invoice",
     input: Schema.Struct({
-      invoiceId: InvoiceId.annotations({ description: "ID of the invoice to delete" }),
+      invoice_id: InvoiceId.annotations({ description: "ID of the invoice to delete" }),
     }),
     output: Schema.Struct({
       deleted: Schema.Boolean.annotations({
@@ -22,7 +22,7 @@ export default defineOperation(
     const raised = await kernel.browsers.playwright.execute(sessionId, {
       timeout_sec: 30,
       code: `
-        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoiceId)}, { exact: true }) });
+        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoice_id)}, { exact: true }) });
         if ((await row.count()) !== 1) return { failure: "invoice_missing" };
         const shown = new Promise((resolve) => page.once("dialog", (dialog) => {
           globalThis.dialog = dialog;
@@ -64,7 +64,7 @@ export default defineOperation(
             : "await globalThis.dialog.dismiss();"
         }
         delete globalThis.dialog;
-        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoiceId)}, { exact: true }) });
+        const row = page.getByRole("row").filter({ has: page.getByText(${JSON.stringify(input.invoice_id)}, { exact: true }) });
         // Read the result back: the row is gone only if the site deleted it.
         await row.waitFor({ state: ${JSON.stringify(decision.choice === "accept" ? "detached" : "visible")}, timeout: 10000 });
         return { deleted: (await row.count()) === 0 };

package/dist/typescript/authoring/examples/navigation.d.ts

@@ -1,12 +1,12 @@
 export declare const detailNavigation: import("../../src/runtime/kernel-operation.js").KernelOperation<{
-    readonly recordId: string;
+    readonly record_id: string;
 }, {
-    readonly recordId: string;
+    readonly record_id: string;
 }, {
-    readonly recordId: string;
+    readonly record_id: string;
     readonly title: string;
 }, {
-    readonly recordId: string;
+    readonly record_id: string;
     readonly title: string;
 }>;
 declare const _default: import("../../src/runtime/kernel-operation.js").KernelOperation<{}, {}, {

package/dist/typescript/authoring/examples/navigation.js

@@ -9,16 +9,19 @@ const Detail = Schema.Union(Schema.Struct({ title: Schema.NonEmptyString }), Sch
 export const detailNavigation = defineOperation({
     name: "read_record_detail",
     input: Schema.Struct({
-        recordId: RecordId.annotations({ description: "ID of the record to read, as in its URL" }),
+        record_id: RecordId.annotations({
+            description: "ID of the record to read, as in its URL",
+            examples: ["record_42"],
+        }),
     }),
     output: Schema.Struct({
-        recordId: RecordId.annotations({ description: "ID of the record read" }),
+        record_id: RecordId.annotations({ description: "ID of the record read" }),
         title: Schema.NonEmptyString.annotations({ description: "The record's title" }),
     }),
 }, async ({ kernel, sessionId, siteOrigin, siteDomain, input, errors }) => {
     if (siteOrigin === undefined)
         throw new errors.OperationFailure("No site origin for a live run", { dispatch: "not_sent" });
-    const target = new URL(`/records/${input.recordId}`, siteOrigin);
+    const target = new URL(`/records/${input.record_id}`, siteOrigin);
     const answer = await kernel.browsers.playwright.execute(sessionId, {
         timeout_sec: 90,
         code: `
@@ -28,7 +31,7 @@ export const detailNavigation = defineOperation({
         const siteDomain = ${JSON.stringify(siteDomain ?? null)};
         const onSite = (url) => siteDomain === null ? url.origin === ${JSON.stringify(siteOrigin)}
           : url.protocol === "https:" && (url.hostname === siteDomain || url.hostname.endsWith("." + siteDomain));
-        const recordId = ${JSON.stringify(input.recordId)};
+        const recordId = ${JSON.stringify(input.record_id)};
         const detail = page.getByRole("region", { name: "Record details", exact: true });
         const interstitial = page.getByRole("region", { name: "Continue to record", exact: true });
         const proceed = interstitial.getByRole("button", { name: "Continue", exact: true });
@@ -81,7 +84,7 @@ export const detailNavigation = defineOperation({
     const result = Schema.decodeUnknownSync(Detail)(answer.result);
     if ("failure" in result)
         throw new errors.OperationFailure(result.failure);
-    return { recordId: input.recordId, title: result.title };
+    return { record_id: input.record_id, title: result.title };
 });
 // A bounded first-page read. A fast exploration load does not remove the readiness wait.
 export default defineOperation({

package/dist/typescript/authoring/examples/navigation.ts

@@ -20,17 +20,20 @@ export const detailNavigation = defineOperation(
   {
     name: "read_record_detail",
     input: Schema.Struct({
-      recordId: RecordId.annotations({ description: "ID of the record to read, as in its URL" }),
+      record_id: RecordId.annotations({
+        description: "ID of the record to read, as in its URL",
+        examples: ["record_42"],
+      }),
     }),
     output: Schema.Struct({
-      recordId: RecordId.annotations({ description: "ID of the record read" }),
+      record_id: RecordId.annotations({ description: "ID of the record read" }),
       title: Schema.NonEmptyString.annotations({ description: "The record's title" }),
     }),
   },
   async ({ kernel, sessionId, siteOrigin, siteDomain, input, errors }) => {
     if (siteOrigin === undefined)
       throw new errors.OperationFailure("No site origin for a live run", { dispatch: "not_sent" });
-    const target = new URL(`/records/${input.recordId}`, siteOrigin);
+    const target = new URL(`/records/${input.record_id}`, siteOrigin);
     const answer = await kernel.browsers.playwright.execute(sessionId, {
       timeout_sec: 90,
       code: `
@@ -40,7 +43,7 @@ export const detailNavigation = defineOperation(
         const siteDomain = ${JSON.stringify(siteDomain ?? null)};
         const onSite = (url) => siteDomain === null ? url.origin === ${JSON.stringify(siteOrigin)}
           : url.protocol === "https:" && (url.hostname === siteDomain || url.hostname.endsWith("." + siteDomain));
-        const recordId = ${JSON.stringify(input.recordId)};
+        const recordId = ${JSON.stringify(input.record_id)};
         const detail = page.getByRole("region", { name: "Record details", exact: true });
         const interstitial = page.getByRole("region", { name: "Continue to record", exact: true });
         const proceed = interstitial.getByRole("button", { name: "Continue", exact: true });
@@ -92,7 +95,7 @@ export const detailNavigation = defineOperation(
       throw new errors.OperationFailure(String(answer.error), { stderr: answer.stderr });
     const result = Schema.decodeUnknownSync(Detail)(answer.result);
     if ("failure" in result) throw new errors.OperationFailure(result.failure);
-    return { recordId: input.recordId, title: result.title };
+    return { record_id: input.record_id, title: result.title };
   },
 );
 

package/dist/typescript/authoring/examples/parser.d.ts

@@ -5,7 +5,7 @@ declare const _default: import("../../src/runtime/kernel-operation.js").KernelOp
 }, {
     readonly invoices: readonly {
         readonly id: string;
-        readonly totalMinor: number;
+        readonly total_minor: number;
         readonly currency: "USD";
     }[];
     readonly complete: boolean;
@@ -14,7 +14,7 @@ declare const _default: import("../../src/runtime/kernel-operation.js").KernelOp
     readonly invoices: readonly {
         readonly currency: "USD";
         readonly id: string;
-        readonly totalMinor: number;
+        readonly total_minor: number;
     }[];
 }>;
 export default _default;

package/dist/typescript/authoring/examples/parser.js

@@ -2,7 +2,7 @@ import { Schema } from "effect";
 import { defineOperation } from "../../src/browser/index.js";
 const Invoice = Schema.Struct({
     id: Schema.NonEmptyString.annotations({ description: "The site's invoice ID" }),
-    totalMinor: Schema.Int.annotations({ description: "Invoice total in cents" }),
+    total_minor: Schema.Int.annotations({ description: "Invoice total in minor units (cents)" }),
     currency: Schema.Literal("USD").annotations({ description: "Currency of the total" }),
 });
 const Body = Schema.Struct({

package/dist/typescript/authoring/examples/parser.ts

@@ -3,7 +3,7 @@ import { defineOperation } from "../../src/browser/index.js";
 
 const Invoice = Schema.Struct({
   id: Schema.NonEmptyString.annotations({ description: "The site's invoice ID" }),
-  totalMinor: Schema.Int.annotations({ description: "Invoice total in cents" }),
+  total_minor: Schema.Int.annotations({ description: "Invoice total in minor units (cents)" }),
   currency: Schema.Literal("USD").annotations({ description: "Currency of the total" }),
 });
 const Body = Schema.Struct({

package/dist/typescript/authoring/examples/write-session.d.ts

@@ -2,48 +2,48 @@ import { Schema } from "effect";
 export declare const OrderInput: Schema.Struct<{
     item: Schema.refine<string, typeof Schema.String>;
     quantity: Schema.refine<number, typeof Schema.Int>;
-    giftWrap: Schema.SchemaClass<boolean, boolean, never>;
+    gift_wrap: Schema.SchemaClass<boolean, boolean, never>;
 }>;
 /** Act step 1: fills the checkout on the site origin page and stops before the commit. */
 export declare const fillStep: import("../../src/runtime/kernel-operation.js").KernelOperation<{
     readonly item: string;
     readonly quantity: number;
-    readonly giftWrap: boolean;
+    readonly gift_wrap: boolean;
 }, {
-    readonly giftWrap: boolean;
+    readonly gift_wrap: boolean;
     readonly item: string;
     readonly quantity: number;
 }, {
-    readonly reviewShown: boolean;
+    readonly review_shown: boolean;
 }, {
-    readonly reviewShown: boolean;
+    readonly review_shown: boolean;
 }>;
 /** Act step 2: continues on the page step 1 left, commits once and reads the confirmation. */
 export declare const placeStep: import("../../src/runtime/kernel-operation.js").KernelOperation<{
     readonly item: string;
     readonly quantity: number;
-    readonly giftWrap: boolean;
+    readonly gift_wrap: boolean;
 }, {
-    readonly giftWrap: boolean;
+    readonly gift_wrap: boolean;
     readonly item: string;
     readonly quantity: number;
 }, {
-    readonly orderNumber: string;
+    readonly order_number: string;
 }, {
-    readonly orderNumber: string;
+    readonly order_number: string;
 }>;
 /** The composed script, published without another run: the whole flow from the site origin page. */
 declare const _default: import("../../src/runtime/kernel-operation.js").KernelOperation<{
     readonly item: string;
     readonly quantity: number;
-    readonly giftWrap: boolean;
+    readonly gift_wrap: boolean;
 }, {
-    readonly giftWrap: boolean;
+    readonly gift_wrap: boolean;
     readonly item: string;
     readonly quantity: number;
 }, {
-    readonly orderNumber: string;
+    readonly order_number: string;
 }, {
-    readonly orderNumber: string;
+    readonly order_number: string;
 }>;
 export default _default;

package/dist/typescript/authoring/examples/write-session.js

@@ -11,15 +11,15 @@ export const OrderInput = Schema.Struct({
     quantity: Schema.Int.pipe(Schema.between(1, 99)).annotations({
         description: "How many to order, 1 to 99",
     }),
-    giftWrap: Schema.Boolean.annotations({ description: "Whether to add gift wrap" }),
+    gift_wrap: Schema.Boolean.annotations({ description: "Whether to add gift wrap" }),
 });
 const Placed = Schema.Struct({
-    orderNumber: Schema.NonEmptyString.annotations({
+    order_number: Schema.NonEmptyString.annotations({
         description: "Order number from the confirmation",
     }),
 });
-const Filled = Schema.Union(Schema.Struct({ reviewShown: Schema.Literal(true) }), Schema.Struct({ failure: Schema.Literal("checkout_changed") }));
-const Confirmed = Schema.Union(Schema.Struct({ orderNumber: Schema.NonEmptyString }), Schema.Struct({ failure: Schema.Literal("review_missing", "not_confirmed") }));
+const Filled = Schema.Union(Schema.Struct({ review_shown: Schema.Literal(true) }), Schema.Struct({ failure: Schema.Literal("checkout_changed") }));
+const Confirmed = Schema.Union(Schema.Struct({ order_number: Schema.NonEmptyString }), Schema.Struct({ failure: Schema.Literal("review_missing", "not_confirmed") }));
 // The act steps and the composed script share these calls, so the published script repeats
 // exactly what the session did.
 /** From the site origin page: open the checkout, fill it from the input and stop at the review step. */
@@ -36,10 +36,10 @@ const fillCheckout = async ({ kernel, sessionId, siteOrigin, input, errors }) =>
       if ((await form.count()) !== 1) return { failure: "checkout_changed" };
       await form.getByLabel("Item", { exact: true }).fill(input.item, { timeout: 5000 });
       await form.getByLabel("Quantity", { exact: true }).fill(String(input.quantity), { timeout: 5000 });
-      await form.getByLabel("Gift wrap", { exact: true }).setChecked(input.giftWrap, { timeout: 5000 });
+      await form.getByLabel("Gift wrap", { exact: true }).setChecked(input.gift_wrap, { timeout: 5000 });
       await form.getByRole("button", { name: "Continue", exact: true }).click({ timeout: 5000 });
       await page.getByRole("button", { name: "Place order", exact: true }).waitFor({ timeout: 10000 });
-      return { reviewShown: true };
+      return { review_shown: true };
     `,
     });
     if (!answer.success)
@@ -63,7 +63,7 @@ const placeAndConfirm = async ({ kernel, sessionId, errors, verified, enteringCo
       const confirmation = page.getByRole("status", { name: "Order confirmation", exact: true });
       try { await confirmation.waitFor({ timeout: 15000 }); } catch { return { failure: "not_confirmed" }; }
       const number = /^Order (ORD-[0-9]+)/.exec(await confirmation.innerText())?.[1];
-      return number === undefined ? { failure: "not_confirmed" } : { orderNumber: number };
+      return number === undefined ? { failure: "not_confirmed" } : { order_number: number };
     `,
     });
     // A failure after the click leaves the write uncertain. Nothing here resubmits it.
@@ -83,11 +83,11 @@ export const fillStep = defineOperation({
     name: "fill_checkout",
     input: OrderInput,
     output: Schema.Struct({
-        reviewShown: Schema.Boolean.annotations({ description: "True once the review step shows" }),
+        review_shown: Schema.Boolean.annotations({ description: "True once the review step shows" }),
     }),
 }, async (context) => {
     await fillCheckout(context);
-    return { reviewShown: true };
+    return { review_shown: true };
 });
 /** Act step 2: continues on the page step 1 left, commits once and reads the confirmation. */
 export const placeStep = defineOperation({ name: "place_order", input: OrderInput, output: Placed }, placeAndConfirm);

package/dist/typescript/authoring/examples/write-session.ts

@@ -13,20 +13,20 @@ export const OrderInput = Schema.Struct({
   quantity: Schema.Int.pipe(Schema.between(1, 99)).annotations({
     description: "How many to order, 1 to 99",
   }),
-  giftWrap: Schema.Boolean.annotations({ description: "Whether to add gift wrap" }),
+  gift_wrap: Schema.Boolean.annotations({ description: "Whether to add gift wrap" }),
 });
 type OrderInput = typeof OrderInput.Type;
 const Placed = Schema.Struct({
-  orderNumber: Schema.NonEmptyString.annotations({
+  order_number: Schema.NonEmptyString.annotations({
     description: "Order number from the confirmation",
   }),
 });
 const Filled = Schema.Union(
-  Schema.Struct({ reviewShown: Schema.Literal(true) }),
+  Schema.Struct({ review_shown: Schema.Literal(true) }),
   Schema.Struct({ failure: Schema.Literal("checkout_changed") }),
 );
 const Confirmed = Schema.Union(
-  Schema.Struct({ orderNumber: Schema.NonEmptyString }),
+  Schema.Struct({ order_number: Schema.NonEmptyString }),
   Schema.Struct({ failure: Schema.Literal("review_missing", "not_confirmed") }),
 );
 type Context = KernelOperationContext<OrderInput>;
@@ -48,10 +48,10 @@ const fillCheckout = async ({ kernel, sessionId, siteOrigin, input, errors }: Co
       if ((await form.count()) !== 1) return { failure: "checkout_changed" };
       await form.getByLabel("Item", { exact: true }).fill(input.item, { timeout: 5000 });
       await form.getByLabel("Quantity", { exact: true }).fill(String(input.quantity), { timeout: 5000 });
-      await form.getByLabel("Gift wrap", { exact: true }).setChecked(input.giftWrap, { timeout: 5000 });
+      await form.getByLabel("Gift wrap", { exact: true }).setChecked(input.gift_wrap, { timeout: 5000 });
       await form.getByRole("button", { name: "Continue", exact: true }).click({ timeout: 5000 });
       await page.getByRole("button", { name: "Place order", exact: true }).waitFor({ timeout: 10000 });
-      return { reviewShown: true };
+      return { review_shown: true };
     `,
   });
   if (!answer.success)
@@ -82,7 +82,7 @@ const placeAndConfirm = async ({
       const confirmation = page.getByRole("status", { name: "Order confirmation", exact: true });
       try { await confirmation.waitFor({ timeout: 15000 }); } catch { return { failure: "not_confirmed" }; }
       const number = /^Order (ORD-[0-9]+)/.exec(await confirmation.innerText())?.[1];
-      return number === undefined ? { failure: "not_confirmed" } : { orderNumber: number };
+      return number === undefined ? { failure: "not_confirmed" } : { order_number: number };
     `,
   });
   // A failure after the click leaves the write uncertain. Nothing here resubmits it.
@@ -104,12 +104,12 @@ export const fillStep = defineOperation(
     name: "fill_checkout",
     input: OrderInput,
     output: Schema.Struct({
-      reviewShown: Schema.Boolean.annotations({ description: "True once the review step shows" }),
+      review_shown: Schema.Boolean.annotations({ description: "True once the review step shows" }),
     }),
   },
   async (context) => {
     await fillCheckout(context);
-    return { reviewShown: true };
+    return { review_shown: true };
   },
 );
 

package/dist/typescript/src/mint/contracts.d.ts

@@ -182,8 +182,12 @@ export declare class MintFailure extends MintFailure_base<{
      | "login_url_one_time"
     /** The login URL to publish carries a registered credential; refused every time. */
      | "login_url_contains_credential"
-    /** The name or description to publish carries a registered credential; refused every time. */
+    /** The name, description, site name or summary to publish carries a registered credential. */
      | "metadata_contains_credential"
+    /** The site's integration has no name yet, and the metadata names no `siteName` and `siteSummary`. */
+     | "site_metadata_required"
+    /** Another enabled tool in the integration this would join has the same tool name. */
+     | "tool_name_taken"
     /** The publication gate refused a file Guardian's review reads; `publicationBlock` names it. */
      | "evidence_screening"
     /** A `read_source` of a capture the workspace does not hold: it is not saved yet. */
@@ -192,7 +196,7 @@ export declare class MintFailure extends MintFailure_base<{
     readonly publicationFeedback?: {
         readonly oneTimeParameters?: readonly string[];
         readonly parts?: readonly {
-            readonly part: "loginUrl" | "name" | "description";
+            readonly part: "loginUrl" | "name" | "description" | "siteName" | "siteSummary";
             readonly credentialKinds: readonly string[];
         }[];
     };
@@ -440,6 +444,9 @@ export declare const PublicationRequest: Schema.Struct<{
     metadata: Schema.Struct<{
         name: typeof Schema.String;
         description: typeof Schema.String;
+        /** Required only while the site's integration has no name yet; a later one is ignored. */
+        siteName: Schema.optional<Schema.refine<string, Schema.filter<Schema.filter<typeof Schema.String>>>>;
+        siteSummary: Schema.optional<Schema.refine<string, Schema.filter<Schema.filter<typeof Schema.String>>>>;
         supportedVariants: Schema.optional<Schema.filter<Schema.filter<Schema.Array$<Schema.Struct<{
             id: Schema.filter<typeof Schema.String>;
             entrypoint: Schema.filter<typeof Schema.String>;

package/dist/typescript/src/mint/contracts.js

@@ -2,6 +2,7 @@ import { CredentialRejectedField } from "../runtime/authentication.js";
 import { IntakeReasonCode } from "../capabilities/intake-contracts.js";
 import { Context, Data, Schema } from "effect";
 import { AutofillPopup, AutofillApproval, DateOfBirthFormat, IdentifierKinds, maximumStepFields, RejectedMarker, SecretSlots, SignInMethodChoice, } from "../destinations/autofill-contracts.js";
+import { SiteNaming } from "../registry/site-naming.js";
 import { SupportedOperationVariant } from "../registry/operation-variants.js";
 import { ChoiceQuestion, ConfirmQuestion, MultiChoiceQuestion, SecretQuestion, TextQuestion, } from "../runtime/input-request.js";
 import { PublicationFinding, PublicationReason } from "../guardian/review-contracts.js";
@@ -152,6 +153,13 @@ export const PublicationRequest = Schema.Struct({
     metadata: Schema.Struct({
         name: Schema.String,
         description: Schema.String,
+        /** Required only while the site's integration has no name yet; a later one is ignored. */
+        siteName: Schema.optional(SiteNaming.fields.name.annotations({
+            description: "The site's everyday name, as people say it, such as Google Flights",
+        })),
+        siteSummary: Schema.optional(SiteNaming.fields.summary.annotations({
+            description: "One sentence on what the site is, not what this tool does",
+        })),
         supportedVariants: Schema.optional(Schema.Array(SupportedOperationVariant).pipe(Schema.minItems(1), Schema.maxItems(32))),
     }),
     coverage: Schema.String,

package/dist/typescript/src/mint/harness.js

@@ -1969,6 +1969,10 @@ export const runMint = (input) => Effect.scoped(Effect.gen(function* () {
                         instruction: "Not published: the source this repair would publish is byte for byte the registered revision's, so there is nothing to publish. A new name or description alone is not a repair. The registered revision stays current and this repair ends here; do not call finish_build again.",
                     });
                 }
+                if (error.reason === "tool_name_taken")
+                    return notPublished(error.code, error.reason, {}, `Not published and not reviewed: ${registryRefusal("tool_name_taken").instruction}`);
+                if (error.reason === "site_metadata_required")
+                    return notPublished(error.code, error.reason, {}, "Not published and not reviewed: this is the first tool of this site's integration, which takes its name from this publication. Add siteName, the site's everyday name as people say it (such as Google Flights, 1 to 60 characters), and siteSummary, one sentence on what the site is, not what this tool does (1 to 160 characters), to finish_build's metadata, and call finish_build again with the same executionId. Both are public: write them from what the site shows anyone, never from this account or session.");
                 if (error.reason === "variants_unsupported")
                     return notPublished(error.code, error.reason, {}, "Not published: this Kernel script declares supportedVariants, and only Effect runs dispatch variants, so every call would fail with InvalidOutput. Either remove supportedVariants from the tool's metadata (keep one script that handles the variation itself) and call finish_build again with the same executionId; the recorded example and result stay valid and nothing needs to run again. Or, if variants are essential, make it an offline tool: execute a new example with target pureFiles, then call finish_build with that new executionId. The same executionId is refused again while its receipt is a Kernel script.");
                 if (error.reason === "http_implementation_untested" ||
@@ -1981,7 +1985,7 @@ export const runMint = (input) => Effect.scoped(Effect.gen(function* () {
                     return notPublished(error.code, error.reason, { ...error.publicationFeedback }, "Not published yet: the login URL this tool would publish (the loginUrl you passed to authenticate, or the page the browser was on when you passed none) is one authorization request: an identity provider's authorize URL, or a URL carrying one-time authorization values (oneTimeParameters names the authorize path and those values). They are spent once this sign-in ends, so later runs that reopen it would start from stale values. The host changed nothing. Navigate the browser to the site's stable sign-in entry, the page a person would bookmark or the site's own login link before it redirected, run authenticate again with that page's address as loginUrl, then call finish_build again with the same executionId. If no stable entry exists, call finish_build again and the host publishes the URL as it is, flagged. The host asks only once.");
                 if (error.reason === "login_url_contains_credential" ||
                     error.reason === "metadata_contains_credential")
-                    return notPublished(error.code, error.reason, { ...error.publicationFeedback }, "Not published: each part named in parts holds a registered credential (credentialKinds names the kind, never the value). A published tool never carries one, and the host changes nothing itself. For loginUrl, run authenticate again with a login URL that has no credential in it, the site's plain sign-in page. For name or description, rewrite the text without it. Then call finish_build again with the same executionId. The host refuses every time until the credential is gone; the build is not over.");
+                    return notPublished(error.code, error.reason, { ...error.publicationFeedback }, "Not published: each part named in parts holds a registered credential (credentialKinds names the kind, never the value). A published tool never carries one, and the host changes nothing itself. For loginUrl, run authenticate again with a login URL that has no credential in it, the site's plain sign-in page. For name, description, siteName or siteSummary, rewrite the text without it. Then call finish_build again with the same executionId. The host refuses every time until the credential is gone; the build is not over.");
                 if (error.reason === "secret_handle") {
                     const path = error.screening?.path ?? "the source";
                     return notPublished(error.code, error.reason, { path: error.screening?.path }, `Not published: ${path} holds a {{secret.…}} handle. A handle works only in this build's own executions, where the host fills in the caller's answer; published code never holds a handle or a value. Declare the value as a secret question in the operation's questions and read it with ask at run time, as .agents/caller-input/SKILL.md shows, then call finish_build again.`);

package/dist/typescript/src/mint/publication-block.js

@@ -30,9 +30,10 @@ const matched = (block) => {
  */
 const definitionFeedback = (block) => {
     const file = "publication/definition.json";
-    const part = block.section ?? "its name, description, schemas or supported variants";
+    const part = block.section ?? "its name, description, site, schemas or supported variants";
     const metadata = block.section === "name" ||
         block.section === "description" ||
+        block.section === "site" ||
         block.section === "supportedVariants";
     const fix = metadata
         ? "Change it in finish_build's metadata, then call finish_build again with the same executionId."

package/dist/typescript/src/mint/registry-feedback.js

@@ -61,6 +61,10 @@ const feedback = {
         fixable: true,
         instruction: "The published tool changed while this build ran: another publication advanced it, and the host did not commit this build over it. If this build should still replace that version, call finish_build again with the same executionId; the host reads the current version and reviews the publication afresh. Otherwise end the build.",
     },
+    tool_name_taken: {
+        fixable: true,
+        instruction: 'Another tool on this site already has this name: tool names are unique within a site\'s integration, and callers pick a tool by its name. Give this tool a name that says what it does differently, a 2–5 word verb phrase such as "Search award flights" beside "Search flights", in finish_build\'s metadata, and call finish_build again with the same executionId.',
+    },
     revision_exists: {
         fixable: false,
         instruction: "The registry already holds a different revision under this build's revision id.",

package/dist/typescript/src/registry/issues.d.ts

@@ -1 +1,3 @@
-export type RegistryIssue = "definition_invalid" | "site_origin_invalid" | "destination_evidence_invalid" | "variants_invalid" | "login_url_without_signed_in_browser" | "login_url_unusable" | "target_mismatch" | "write_confirmation_on_read" | "catalog_generation_invalid" | "attempt_stopped" | "catalog_moved" | "variant_removed" | "variant_contract_changed" | "generation_moved" | "revision_exists";
+export type RegistryIssue = "definition_invalid" | "site_origin_invalid" | "destination_evidence_invalid" | "variants_invalid" | "login_url_without_signed_in_browser" | "login_url_unusable" | "target_mismatch" | "write_confirmation_on_read" | "catalog_generation_invalid" | "attempt_stopped" | "catalog_moved" | "variant_removed" | "variant_contract_changed" | "generation_moved" | "revision_exists"
+/** Another enabled tool in the integration has the same tool name. */
+ | "tool_name_taken";

package/dist/typescript/src/registry/site-naming.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** A website integration's site: its everyday name ("Google Flights") and what the site is, never its tools. */
+export declare const SiteNaming: Schema.Struct<{
+    name: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    summary: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+}>;
+export type SiteNaming = typeof SiteNaming.Type;

package/dist/typescript/src/registry/site-naming.js

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+/** A website integration's site: its everyday name ("Google Flights") and what the site is, never its tools. */
+export const SiteNaming = Schema.Struct({
+    name: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(60), Schema.pattern(/\S/)),
+    summary: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(160), Schema.pattern(/\S/)),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pomerado",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pomerado's integration minter and Guardian with local compute and native Playwright",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -586,6 +586,11 @@
       "types": "./dist/typescript/authoring/examples/write-session.d.ts",
       "import": "./dist/typescript/authoring/examples/write-session.js",
       "default": "./dist/typescript/authoring/examples/write-session.js"
+    },
+    "./core/registry/site-naming": {
+      "types": "./dist/typescript/src/registry/site-naming.d.ts",
+      "import": "./dist/typescript/src/registry/site-naming.js",
+      "default": "./dist/typescript/src/registry/site-naming.js"
     }
   },
   "files": [