@spacefast/common 0.0.13 → 0.0.18

package/dist/contracts/common.d.ts

@@ -102,19 +102,19 @@ export declare const requiredActionsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[
     type: z.ZodLiteral<"renew">;
     domainId: z.ZodString;
 }, z.core.$strip>], "type">>;
-export declare const ApiErrorResponseSchema: z.ZodObject<{
-    error: z.ZodObject<{
-        code: z.ZodString;
-        message: z.ZodString;
-        param: z.ZodOptional<z.ZodString>;
-        docsUrl: z.ZodString;
-        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        suggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        next: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        requestId: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
+export declare const ProblemDetailsSchema: z.ZodObject<{
+    type: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodNumber;
+    detail: z.ZodString;
+    code: z.ZodString;
+    pointer: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    next: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requestId: z.ZodString;
 }, z.core.$strip>;
-export type ApiErrorResponse = z.infer<typeof ApiErrorResponseSchema>;
+export type ProblemDetails = z.infer<typeof ProblemDetailsSchema>;
 export declare function dataEnvelope<T extends z.ZodType>(data: T): z.ZodObject<{
     data: T;
 }, z.core.$strip>;

package/dist/contracts/common.js

@@ -18,7 +18,7 @@ export const baseDiagnosticSchema = z.object({
     path: z
         .string()
         .nullish()
-        .describe('Artifact path the diagnostic points at, e.g. "_headers:12", when one exists.'),
+        .describe('Artifact path the diagnostic points at, for example "_headers:12", when one exists.'),
     provider: diagnosticProvider
         .nullish()
         .describe("Upstream system the diagnostic originated from, when not Spacefast itself."),
@@ -30,7 +30,7 @@ export const baseDiagnosticSchema = z.object({
     retryable: z
         .boolean()
         .nullish()
-        .describe("Whether retrying the same operation may resolve this diagnostic without the caller changing anything."),
+        .describe("Whether retrying the same operation can resolve this diagnostic without the caller changing anything."),
 });
 // Canonical DnsInstruction (internal-docs/platform.md L2500-2506): provider vocabulary
 // never leaks into `purpose`.
@@ -64,31 +64,34 @@ export const requiredActionSchema = z.discriminatedUnion("type", [
 export const requiredActionsSchema = z
     .array(requiredActionSchema)
     .describe("Concrete user steps that unblock this resource, using the one shared vocabulary.");
-// The error envelope (internal-docs/platform.md "Global API Conventions"): `docsUrl` is
-// mandatory and derived from `code` (see contracts/error-codes.ts); `param` is a
-// JSON-path-lite pointer into the failing request field on validation failures.
-export const ApiErrorResponseSchema = z.object({
-    error: z.object({
-        code: z.string().describe("Stable snake_case error code naming the failed public contract."),
-        message: z.string().describe("Human-readable failure explanation."),
-        param: z
-            .string()
-            .optional()
-            .describe('JSON-path-lite pointer into the failing request field, e.g. "files[37].path", on validation failures.'),
-        docsUrl: z
-            .string()
-            .describe("Always present; derived mechanically from `code` against the docs origin."),
-        details: AnyObjectSchema.optional().describe("Machine-readable context for the error code."),
-        suggestions: z
-            .array(z.string())
-            .optional()
-            .describe("Actionable recovery steps safe to show in dashboards, SDKs, and CLI output."),
-        next: z
-            .array(z.string())
-            .optional()
-            .describe("Copy-pasteable commands or API requests an agent can run next."),
-        requestId: z.string().optional().describe("Request id to quote when contacting support."),
-    }),
+// The error shape (internal-docs/platform.md "Global API Conventions"): every 4xx/5xx body
+// is one RFC 9457 problem details document served as `application/problem+json`. `type` and
+// `title` are derived mechanically from `code` (see contracts/error-codes.ts); `code`,
+// `pointer` (RFC 6901), `details`, `suggestions`, `next`, and `requestId` are extension members.
+export const ProblemDetailsSchema = z.object({
+    type: z
+        .string()
+        .describe("Problem type URI. It resolves to the error docs page. The server derives it mechanically from `code` against the docs origin."),
+    title: z
+        .string()
+        .describe("Short human-readable summary of the problem type. The server derives it mechanically from `code`."),
+    status: z.number().int().describe("HTTP status code of this response, repeated in the body."),
+    detail: z.string().describe("Human-readable failure explanation for this occurrence."),
+    code: z.string().describe("Stable snake_case error code naming the failed public contract."),
+    pointer: z
+        .string()
+        .optional()
+        .describe('RFC 6901 JSON Pointer into the failing request field, for example "/files/37/path", on validation failures.'),
+    details: AnyObjectSchema.optional().describe("Machine-readable context for the error code."),
+    suggestions: z
+        .array(z.string())
+        .optional()
+        .describe("Actionable recovery steps safe to show in dashboards, SDKs, and CLI output."),
+    next: z
+        .array(z.string())
+        .optional()
+        .describe("Copy-pasteable commands or API requests an agent can run next."),
+    requestId: z.string().describe("The request id to quote when contacting support."),
 });
 // Success envelope (internal-docs/platform.md "Global API Conventions"): `{ data: T }` for
 // single resources and mutations, `{ data: T[], pagination }` for lists. Mutations whose work
@@ -98,7 +101,7 @@ export function dataEnvelope(data) {
 }
 export const ApiUploadInstructionSchema = z
     .object({
-    id: z.string().describe("Upload session id (`upl_…`)."),
+    id: z.string().describe("The upload session id (`upl_…`)."),
     expiresAt: z.string().datetime(),
     method: z.literal("PUT"),
     url: z
@@ -114,7 +117,7 @@ export const CursorPaginationSchema = z.object({
     nextCursor: z
         .string()
         .nullable()
-        .describe("Opaque cursor for the next page; pass as `?cursor=`. Null on the last page."),
+        .describe("Opaque cursor for the next page; null when there are no more results."),
     hasMore: z.boolean().describe("Whether another page exists after this one."),
 });
 export const CURSOR_MAX_LENGTH = 4_096;
@@ -133,7 +136,7 @@ export const cursorListQuerySchema = z.object({
         .min(1)
         .max(CURSOR_MAX_LENGTH)
         .optional()
-        .describe("Opaque cursor from a previous page's `pagination.nextCursor`."),
+        .describe("Opaque cursor from the previous page's `nextCursor`."),
 });
 // The operator-only offset list-response shape (superadmin surfaces): the named
 // items array, plus `total`/`limit`/`offset` and the offset `pagination` block.

package/dist/contracts/continuation.js

@@ -13,7 +13,7 @@ import { AnyObjectSchema } from "./common.js";
 // generalized resume endpoint once the human step is done.
 export const RequiresActionTypeSchema = z
     .enum(["device_authorization"])
-    .describe("Stable identifier for the out-of-band step a flow is blocked on. New blocking steps are added HERE so resume stays one generalized contract.");
+    .describe("Stable identifier for the out-of-band step that blocks the flow. Add new blocking steps here so resume stays one generalized contract.");
 export const RequiresActionSchema = z
     .object({
     actionType: RequiresActionTypeSchema,
@@ -29,7 +29,7 @@ export const RequiresActionSchema = z
     continuationToken: z
         .string()
         .min(1)
-        .describe("Short-lived, single-use-on-completion, principal-scoped capability the agent presents to POST /v1/actions/resume to poll and complete this exact flow. Treat as a secret; never log it."),
+        .describe("Short-lived, principal-scoped capability for this exact flow. Present it to POST /v1/actions/resume to poll and complete the flow. The token is single-use on completion. Treat it as a secret. Never log it."),
     pollAfterSeconds: z
         .number()
         .int()
@@ -38,7 +38,7 @@ export const RequiresActionSchema = z
     expiresAt: z
         .string()
         .datetime()
-        .describe("Instant by which the human step must be completed — the originating flow's own deadline. Resume after this returns a terminal `expired` status (the token survives a short grace past this so resume can report that), but the flow can no longer be redeemed."),
+        .describe("Instant when the human step deadline is reached for the originating flow. Resume after this returns terminal `expired`. The token survives for a short grace so resume can report `expired`, but the flow can no longer be redeemed."),
 })
     .strict();
 /** The canonical `{ requiresAction }` envelope, additive alongside `{ data }` / `{ error }`. */
@@ -70,7 +70,7 @@ export const ActionResumeResponseSchema = z
         .object({
         status: z.literal("completed"),
         actionType: RequiresActionTypeSchema,
-        result: AnyObjectSchema.describe("The flow's success payload, redeemed exactly once. For device_authorization this carries the one-time `apiKey` and any `claimedSpaceId`."),
+        result: AnyObjectSchema.describe("Flow success payload, redeemed exactly once. For device_authorization, this carries the one-time `apiKey` and any `claimedSpaceId`."),
     })
         .strict(),
     z
@@ -88,4 +88,4 @@ export const ActionResumeResponseSchema = z
     })
         .strict(),
 ])
-    .describe("Consistent resume result across flows: keep polling on `pending`, read the one-time payload on `completed`, stop on `denied`/`expired`.");
+    .describe("Consistent resume result across flows. Keep polling on `pending`. Read the one-time payload on `completed`. Stop on `denied` or `expired`.");

package/dist/contracts/data-source-routes.js

@@ -4,7 +4,7 @@ import { dataSourceNameSchema, wordpressDataSourceSchema } from "./space-config.
 export const dataSourceListItemSchema = wordpressDataSourceSchema
     .extend({
     name: dataSourceNameSchema,
-    default: z.boolean().describe("True for the effective default source."),
+    default: z.boolean().describe("Whether this source is the effective default."),
 })
     .strict();
 export const dataSourceListResponseSchema = dataEnvelope(z.object({

package/dist/contracts/device-auth.d.ts

@@ -199,9 +199,9 @@ export declare const AgentHandoffCreateRequestSchema: z.ZodObject<{
     spaceId: z.ZodString;
     clientTargetId: z.ZodEnum<{
         "claude-code": "claude-code";
+        codex: "codex";
         cursor: "cursor";
         vscode: "vscode";
-        codex: "codex";
     }>;
 }, z.core.$strict>;
 export type AgentHandoffCreateRequest = z.infer<typeof AgentHandoffCreateRequestSchema>;
@@ -213,9 +213,9 @@ export declare const AgentHandoffCreateResponseSchema: z.ZodObject<{
     spaceId: z.ZodString;
     clientTargetId: z.ZodEnum<{
         "claude-code": "claude-code";
+        codex: "codex";
         cursor: "cursor";
         vscode: "vscode";
-        codex: "codex";
     }>;
 }, z.core.$strict>;
 export type AgentHandoffCreateResponse = z.infer<typeof AgentHandoffCreateResponseSchema>;
@@ -223,9 +223,9 @@ export declare const AgentHandoffRedeemRequestSchema: z.ZodObject<{
     url: z.ZodString;
     clientTargetId: z.ZodOptional<z.ZodEnum<{
         "claude-code": "claude-code";
+        codex: "codex";
         cursor: "cursor";
         vscode: "vscode";
-        codex: "codex";
     }>>;
 }, z.core.$strict>;
 export type AgentHandoffRedeemRequest = z.infer<typeof AgentHandoffRedeemRequestSchema>;
@@ -342,9 +342,9 @@ export declare const AgentHandoffRedeemResponseSchema: z.ZodObject<{
     spaceId: z.ZodString;
     clientTargetId: z.ZodEnum<{
         "claude-code": "claude-code";
+        codex: "codex";
         cursor: "cursor";
         vscode: "vscode";
-        codex: "codex";
     }>;
 }, z.core.$strict>;
 export type AgentHandoffRedeemResponse = z.infer<typeof AgentHandoffRedeemResponseSchema>;
@@ -367,9 +367,9 @@ export declare const AgentHandoffSummarySchema: z.ZodObject<{
     spaceId: z.ZodString;
     clientTargetId: z.ZodEnum<{
         "claude-code": "claude-code";
+        codex: "codex";
         cursor: "cursor";
         vscode: "vscode";
-        codex: "codex";
     }>;
     status: z.ZodEnum<{
         revoked: "revoked";
@@ -388,9 +388,9 @@ export declare const AgentHandoffListResponseSchema: z.ZodArray<z.ZodObject<{
     spaceId: z.ZodString;
     clientTargetId: z.ZodEnum<{
         "claude-code": "claude-code";
+        codex: "codex";
         cursor: "cursor";
         vscode: "vscode";
-        codex: "codex";
     }>;
     status: z.ZodEnum<{
         revoked: "revoked";

package/dist/contracts/device-auth.js

@@ -172,8 +172,8 @@ export const DeviceAuthorizationDenyResponseSchema = z.object({
 export const AGENT_HANDOFF_CLIENT_TARGETS = ["claude-code", "codex", "cursor", "vscode"];
 export const AgentHandoffCreateRequestSchema = z
     .object({
-    teamId: z.string().min(1).describe("Team that owns the selected Space."),
-    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    teamId: z.string().min(1).describe("Team that owns the selected space."),
+    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
     clientTargetId: z
         .enum(AGENT_HANDOFF_CLIENT_TARGETS)
         .describe("CLI-redeemable client family the handoff is bound to."),
@@ -185,13 +185,13 @@ export const AgentHandoffCreateResponseSchema = z
     url: z
         .string()
         .url()
-        .describe("Sensitive one-time handoff URL. This is the only response field containing the fragment secret."),
+        .describe("Sensitive one-time handoff URL. This is the only response field containing the browser credential."),
     expiresAt: z
         .string()
         .datetime()
         .describe("Instant after which the handoff cannot be redeemed."),
-    teamId: z.string().min(1).describe("Team that owns the selected Space."),
-    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    teamId: z.string().min(1).describe("Team that owns the selected space."),
+    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
     clientTargetId: z
         .enum(AGENT_HANDOFF_CLIENT_TARGETS)
         .describe("CLI-redeemable client family the handoff is bound to."),
@@ -212,9 +212,9 @@ export const AgentHandoffRedeemRequestSchema = z
 export const AgentHandoffRedeemResponseSchema = z
     .object({
     status: z.literal("redeemed").describe("The handoff was redeemed exactly once."),
-    apiKey: ApiKeySchema.describe("Finite Space-scoped API key including its one-time secret."),
-    teamId: z.string().min(1).describe("Team that owns the selected Space."),
-    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    apiKey: ApiKeySchema.describe("Finite space-scoped API key including its one-time secret."),
+    teamId: z.string().min(1).describe("Team that owns the selected space."),
+    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
     clientTargetId: z
         .enum(AGENT_HANDOFF_CLIENT_TARGETS)
         .describe("CLI-redeemable client family the handoff is bound to."),
@@ -228,19 +228,19 @@ export const AgentHandoffRevokeResponseSchema = z
 // List (`GET /v1/auth/agent-handoffs?teamId=…`): the human handoff ledger. Session-only,
 // scoped to one team, bounded to the newest rows (active handoffs are few and short-lived,
 // so the bound can never hide a revocable link); rows are the truthful lifecycle record,
-// never the secret (the fragment secret exists only in the one create response and is
+// never the secret (the browser credential exists only in the one create response and is
 // never listed or replayed).
 export const AgentHandoffListQuerySchema = z.object({
     teamId: z.string().min(1).describe("Team whose issued agent handoffs to list."),
 });
 export const AgentHandoffStatusSchema = z
     .enum(["pending", "redeemed", "revoked"])
-    .describe("Stored lifecycle status. `expired` is not a stored status — it is derived by the caller from `expiresAt`.");
+    .describe("Stored lifecycle status. `expired` is not a stored status. The caller derives it from `expiresAt`.");
 export const AgentHandoffSummarySchema = z
     .object({
     id: z.string().min(1).describe("Opaque app-private handoff document identifier."),
-    teamId: z.string().min(1).describe("Team that owns the selected Space."),
-    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    teamId: z.string().min(1).describe("Team that owns the selected space."),
+    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
     clientTargetId: z
         .enum(AGENT_HANDOFF_CLIENT_TARGETS)
         .describe("CLI-redeemable client family the handoff is bound to."),

package/dist/contracts/docs.d.ts

@@ -9,12 +9,12 @@ export declare const docsIndexQuerySchema: z.ZodObject<{
         reference: "reference";
     }>>;
     category: z.ZodOptional<z.ZodEnum<{
-        api: "api";
         guide: "guide";
+        api: "api";
         error: "error";
         cli: "cli";
-        recipe: "recipe";
         workflow: "workflow";
+        recipe: "recipe";
     }>>;
 }, z.core.$strip>;
 /** Links carried by every docs entry. */
@@ -28,12 +28,12 @@ export declare const DocsEntrySchema: z.ZodObject<{
     title: z.ZodString;
     summary: z.ZodString;
     category: z.ZodEnum<{
-        api: "api";
         guide: "guide";
+        api: "api";
         error: "error";
         cli: "cli";
-        recipe: "recipe";
         workflow: "workflow";
+        recipe: "recipe";
     }>;
     tier: z.ZodEnum<{
         essential: "essential";
@@ -54,12 +54,12 @@ export declare const DocsDocSchema: z.ZodObject<{
     title: z.ZodString;
     summary: z.ZodString;
     category: z.ZodEnum<{
-        api: "api";
         guide: "guide";
+        api: "api";
         error: "error";
         cli: "cli";
-        recipe: "recipe";
         workflow: "workflow";
+        recipe: "recipe";
     }>;
     tier: z.ZodEnum<{
         essential: "essential";
@@ -84,12 +84,12 @@ export declare const DocsIndexResponseSchema: z.ZodObject<{
     }>;
     query: z.ZodNullable<z.ZodString>;
     category: z.ZodNullable<z.ZodEnum<{
-        api: "api";
         guide: "guide";
+        api: "api";
         error: "error";
         cli: "cli";
-        recipe: "recipe";
         workflow: "workflow";
+        recipe: "recipe";
     }>>;
     count: z.ZodNumber;
     entries: z.ZodArray<z.ZodObject<{
@@ -97,12 +97,12 @@ export declare const DocsIndexResponseSchema: z.ZodObject<{
         title: z.ZodString;
         summary: z.ZodString;
         category: z.ZodEnum<{
-            api: "api";
             guide: "guide";
+            api: "api";
             error: "error";
             cli: "cli";
-            recipe: "recipe";
             workflow: "workflow";
+            recipe: "recipe";
         }>;
         tier: z.ZodEnum<{
             essential: "essential";

package/dist/contracts/domains.js

@@ -14,17 +14,17 @@ export const domainRegistrarFacetSchema = z.object({
     provider: z
         .string()
         .optional()
-        .describe('Wrapped registrar provider key when mode is "stattic", e.g. "wpcom".'),
+        .describe("Wrapped registrar provider key when `mode` is `stattic`, for example `wpcom`."),
     status: z
         .enum(["active", "pending_purchase", "pending_transfer_in", "expiring", "expired", "locked"])
         .optional()
         .describe("Registration lifecycle status; `expiring` is derived from the expiry date."),
-    expiresAt: z.string().datetime().optional().describe("When the registration expires."),
+    expiresAt: z.string().datetime().optional().describe("Instant when the registration expires."),
     redemptionEndsAt: z
         .string()
         .datetime()
         .optional()
-        .describe("End of the provider grace/redemption window after expiry."),
+        .describe("Instant when the provider grace or redemption window ends after expiry."),
     autoRenew: z.boolean().optional().describe("Whether the registration renews automatically."),
     transferLock: z
         .boolean()
@@ -40,15 +40,15 @@ export const domainDnsFacetSchema = z.object({
     managementKind: z
         .enum(["unmanaged_external", "connected_provider", "registrar_dns", "stattic_nameservers"])
         .optional()
-        .describe("Derived DNS management state. Additive; `mode` remains the v1 compatibility field."),
+        .describe("Derived DNS management state. This field is additive. `mode` remains the v1 compatibility field."),
     dnsMode: z
         .enum(["authoritative", "adapter"])
         .optional()
-        .describe("Hybrid DNS mode derived from `managementKind`: authoritative (Spacefast hosts the zone) or adapter (records managed/observed on the user's existing host). Additive read-model label."),
+        .describe("Hybrid DNS mode derived from `managementKind`: authoritative when Spacefast hosts the zone, or adapter when records are managed or observed on the user's existing host. This field is an additive read-model label."),
     provider: z
         .string()
         .optional()
-        .describe('Wrapped DNS provider key when mode is "stattic", e.g. "route53" or "wpcom".'),
+        .describe("Wrapped DNS provider key when `mode` is `stattic`, for example `route53` or `wpcom`."),
     assignedNameservers: z
         .array(z.string())
         .optional()
@@ -88,13 +88,13 @@ export const domainVerificationSchema = z.object({
         .datetime()
         .nullable()
         .optional()
-        .describe("When observed DNS was last polled."),
+        .describe("Instant when observed DNS was last polled."),
     lastVerifiedAt: z
         .string()
         .datetime()
         .nullable()
         .optional()
-        .describe("Last time this domain proved DNS control."),
+        .describe("Instant when this domain last proved DNS control."),
     diagnostics: z
         .array(baseDiagnosticSchema)
         .optional()
@@ -171,7 +171,7 @@ export const domainRedirectTargetSchema = z
     .describe("Redirect destination: an absolute URL, or a space (optionally with a path).");
 export const domainRedirectStatusSchema = z
     .union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)])
-    .describe("HTTP redirect status; defaults to 308.");
+    .describe("HTTP redirect status. Defaults to 308.");
 // A domain either serves its Space or redirects away from it — whole-host
 // only. Path-level routing belongs in the serving Space's `_redirects`.
 export const domainRedirectSchema = z.object({
@@ -191,10 +191,10 @@ export const DomainSchema = z.object({
         .describe("Read-only U-label form, present only when it differs from `name`."),
     kind: z
         .enum(["hostname", "apex"])
-        .describe("Derived, never create input: `apex` iff `name` equals `derivedGroup`."),
+        .describe("Derived field, never create input: `apex` if and only if `name` equals `derivedGroup`."),
     wildcardEnabled: z
         .boolean()
-        .describe("Whether wildcard hostnames may be derived from this record."),
+        .describe("Whether wildcard hostnames can be derived from this record."),
     spaceId: z
         .string()
         .nullable()
@@ -219,8 +219,8 @@ export const DomainSchema = z.object({
         .array(domainHintSchema)
         .optional()
         .describe("Projected domain hints derived from diagnostics, actions, observations, and operations."),
-    createdAt: z.string().datetime().describe("When the record was created."),
-    updatedAt: z.string().datetime().describe("When the record last changed."),
+    createdAt: z.string().datetime().describe("Instant when the record was created."),
+    updatedAt: z.string().datetime().describe("Instant when the record last changed."),
 });
 export const domainListQuerySchema = cursorListQuerySchema.extend({
     teamId: z.string().min(1).optional().describe("Filter to domains owned by one team."),
@@ -242,7 +242,7 @@ export const spaceManagedDomainSchema = z.object({
     managed: z.literal(true),
     deletable: z.literal(false),
     assignable: z.literal(false),
-    primary: z.boolean().describe("True when no custom primary domain overrides the managed URL."),
+    primary: z.boolean().describe("Whether no custom primary domain overrides the managed URL."),
     name: z.string().describe("Managed hostname."),
     unicodeName: z.string().optional(),
     kind: z.literal("hostname"),
@@ -281,7 +281,7 @@ export const domainCreateRequestSchema = z.object({
         .string()
         .min(1)
         .optional()
-        .describe("Owning team. Defaults to the active team for sessions and the key's team."),
+        .describe("Owning team. Defaults to the active team for sessions and the API key's team."),
 });
 // Facet modes are never PATCHable: `dns.mode` changes only via POST /dns and
 // `registrar.mode` only via POST /registration. The PATCHable surface is
@@ -291,7 +291,7 @@ export const domainPatchSchema = z
     wildcardEnabled: z
         .boolean()
         .optional()
-        .describe("Allow wildcard bindings under this domain record."),
+        .describe("Pass `true` to allow wildcard bindings under this domain record. Pass `false` to disallow them."),
 })
     .refine((value) => Object.keys(value).length > 0, {
     message: "At least one domain field is required.",
@@ -306,14 +306,14 @@ export const domainRegistrationSchema = z.object({
     provider: z
         .enum(["dsapi", "manual"])
         .nullable()
-        .describe("Wrapped registrar bridge the registration lives at."),
+        .describe("Wrapped registrar bridge where the registration lives."),
     status: z.string().describe("Registration lifecycle status."),
-    expiresAt: z.string().datetime().nullable().describe("When the registration expires."),
+    expiresAt: z.string().datetime().nullable().describe("Instant when the registration expires."),
     redemptionEndsAt: z
         .string()
         .datetime()
         .nullable()
-        .describe("End of the redemption window after expiry."),
+        .describe("Instant when the redemption window ends after expiry."),
     autoRenew: z.boolean().describe("Whether the registration renews automatically."),
     transferLock: z.boolean().describe("Whether outbound transfers are locked."),
     privacySetting: z
@@ -321,7 +321,7 @@ export const domainRegistrationSchema = z.object({
         .nullable()
         .describe("WHOIS privacy behavior."),
     contactId: z.string().nullable().describe("Registrant contact record."),
-    failureReason: z.string().nullable().describe("Provider failure detail, when failed."),
+    failureReason: z.string().nullable().describe("Provider failure detail when status is `failed`."),
     createdAt: z.string().datetime().nullable(),
     updatedAt: z.string().datetime().nullable(),
 });
@@ -377,8 +377,14 @@ export const domainRegistrationActionSchema = z.discriminatedUnion("action", [
 export const domainRegistrationActionResponseSchema = mutationEnvelope(domainRegistrationSchema);
 export const domainRegistrationPatchSchema = z
     .object({
-    autoRenew: z.boolean().optional().describe("Toggle automatic renewal."),
-    transferLock: z.boolean().optional().describe("Toggle the registrar transfer lock."),
+    autoRenew: z
+        .boolean()
+        .optional()
+        .describe("Pass `true` to enable automatic renewal. Pass `false` to disable it."),
+    transferLock: z
+        .boolean()
+        .optional()
+        .describe("Pass `true` to enable the registrar transfer lock. Pass `false` to disable it."),
     privacySetting: z
         .enum(["enable_privacy_service", "redact_contact_info", "disclose_contact_info"])
         .optional()
@@ -427,7 +433,7 @@ export const domainNameserverUpdateSchema = z.object({
 export const domainDnsModeRequestSchema = z.object({
     mode: z
         .enum(["stattic", "external"])
-        .describe("Target DNS hosting mode. external→stattic snapshots observed records first."),
+        .describe("Target DNS hosting mode. On `external` to `stattic`, the server snapshots observed records first."),
 });
 // The transition receipt rides inside `data` (envelope law: `{data}` plus
 // `operation` only): the post-mutation Domain plus the transition diagnostics
@@ -473,11 +479,11 @@ export const domainDnsRecordSchema = z.object({
         .describe("Provider-only record metadata when advertised by capabilities."),
     managed: z
         .boolean()
-        .describe("Spacefast-owned (verification/routing/ssl); read-only via the public API."),
+        .describe("Whether Spacefast owns this record for verification, routing, or SSL. Set by the server; read-only."),
     protected: z
         .boolean()
         .default(false)
-        .describe("Read-only through public DNS record writes even when the record is not Spacefast-owned."),
+        .describe("Whether this record is read-only through public DNS record writes, even when Spacefast does not own it."),
     purpose: z
         .enum(["verification", "routing", "ssl"])
         .nullable()
@@ -497,8 +503,8 @@ export const domainDnsCapabilityFieldSchema = z.object({
         .enum(["string", "number", "boolean", "enum", "object", "array"])
         .describe("Machine-readable field type."),
     readable: z.boolean().describe("Whether provider snapshots can return this field."),
-    creatable: z.boolean().describe("Whether create requests may set this field."),
-    patchable: z.boolean().describe("Whether patch requests may change this field."),
+    creatable: z.boolean().describe("Whether create requests can set this field."),
+    patchable: z.boolean().describe("Whether patch requests can change this field."),
     requiredWhen: z
         .string()
         .nullable()
@@ -655,7 +661,7 @@ export const domainDnsCapabilitiesSchema = z
         "delegated_nameservers",
         "internal_service_key",
     ])
-        .describe("Why DNS writes are or are not available."),
+        .describe("Why DNS writes are available or unavailable."),
     provider: z.string().nullable().describe("Effective DNS provider key when known."),
     recordTypes: z
         .array(domainDnsRecordSchema.shape.type)
@@ -944,7 +950,7 @@ export const domainActionCreateRequestSchema = domainActionDraftSchema.extend({
         .min(1)
         .max(320)
         .optional()
-        .describe("Stable caller-supplied dedupe key; server derives one when omitted."),
+        .describe("Stable caller-supplied dedupe key. The server derives one when you omit this field."),
 });
 export const domainActionMutationResponseSchema = mutationEnvelope(domainActionSchema);
 export const domainDnsRecordSnapshotMetadataSchema = z.object({
@@ -1064,7 +1070,7 @@ const domainDnsRecordPatchableFields = z.object({
         .int()
         .min(60)
         .max(86400)
-        .describe("Time to live in seconds (60-86400); defaults to 3600 on create."),
+        .describe("Time to live in seconds (60 to 86400). Defaults to 3600 on create."),
     priority: z
         .number()
         .int()
@@ -1095,8 +1101,8 @@ export const domainDnsRecordPatchSchema = domainDnsRecordPatchableFields
 })
     .superRefine(requireMxSrvPriority);
 // Executed in exactly this order — deletes, patches, puts, posts — as one
-// atomic transaction; any failure rejects the whole batch with the failing
-// entry in `error.param`.
+// atomic transaction; any failure rejects the whole batch with an RFC 6901
+// JSON Pointer to the failing entry in the problem document's `pointer`.
 export const domainDnsRecordBatchSchema = z
     .object({
     deletes: z
@@ -1188,7 +1194,7 @@ export const domainDiagnosticsResponseSchema = z.object({
     diagnostics: z
         .array(baseDiagnosticSchema)
         .optional()
-        .describe('Domain-level setup nudges computed at read time, e.g. "companion_hostname_unbound" when the apex/www pair is half-bound.'),
+        .describe('Domain-level setup nudges computed at read time, for example "companion_hostname_unbound" when the apex/www pair is half-bound.'),
     hostnameDiagnostics: z
         .array(domainHostnameDiagnosticsSchema)
         .describe("Per-hostname DNS and SSL connectivity diagnostics."),