@spacefast/common 0.0.12 → 0.0.17

package/dist/contracts/activity.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const ACTIVITY_EVENT_CODES: readonly ["space.created", "space.claimed", "feedback.lead_claim_pending", "space.transferred", "space.move_requested", "space.moved", "space.expired", "space.disabled", "space.enabled", "space.deleted", "space.config_updated", "space.slug_updated", "space.password_updated", "site.provision_requested", "site.placement_hold_set", "site.placement_hold_cleared", "site.burst_toggled", "space.access_logout_all", "space.access_transfer_scrub", "space.access_operator_token", "space.sharing_updated", "space.share_link_created", "space.share_link_revoked", "space.invite_created", "space.invite_revoked", "space.access_request_created", "space.access_request_resolved", "space.firewall_updated", "team.access_defaults_updated", "team.service_token_created", "team.service_token_revoked", "team.access_connection_created", "team.access_connection_updated", "team.access_connection_revoked", "version.created", "version.ready", "version.warning", "version.failed", "version.expired", "version.canceled", "version.deleted", "version.retention_warning", "version.retention_deleted", "channel.promoted", "build.created", "build.succeeded", "build.failed", "build.canceled", "build.skipped", "domain.created", "domain.verified", "domain.verification_failed", "domain.control_lost", "domain.dns_updated", "domain.nameservers_updated", "domain.registration_purchased", "domain.registration_renewed", "domain.registration_expiring", "domain.registration_expired", "domain.transfer_in_started", "domain.transfer_out_started", "domain.deleted", "domain.attached", "domain.activated", "domain.blocked", "domain.detached", "transfer.requested", "transfer.confirmed", "transfer.completed", "transfer.canceled", "transfer.expired", "transfer.failed", "variable.updated", "variable.deleted", "api_key.created", "api_key.updated", "api_key.revoked", "agent_handoff.created", "agent_handoff.redeemed", "agent_handoff.revoked", "webhook.created", "webhook.updated", "webhook.secret_rotated", "webhook.disabled", "webhook.deleted", "team.updated", "team.slug_updated", "team.member_added", "team.member_removed", "team.member_role_updated", "team.builds_deploys_quota_exceeded", "tenant.past_due", "tenant.suspended", "tenant.reactivated", "tenant.deleted", "export.ready", "export.failed", "import.ready", "import.failed", "comment.token_minted", "comment.created", "comment.reply_created", "comment.archived", "comment.unarchived", "abuse_report.created", "abuse_report.updated", "claim.blocked_takedown", "user.created", "user.signed_in", "user.deleted", "user.impersonation_started", "user.impersonation_stopped", "user.two_factor_enabled", "user.two_factor_disabled"];
+export declare const ACTIVITY_EVENT_CODES: readonly ["space.created", "space.claimed", "feedback.lead_claim_pending", "space.transferred", "space.move_requested", "space.moved", "space.expired", "space.disabled", "space.enabled", "space.deleted", "space.config_updated", "space.slug_updated", "site.provision_requested", "site.placement_hold_set", "site.placement_hold_cleared", "site.burst_toggled", "space.access_logout_all", "space.access_transfer_scrub", "space.share_link_created", "space.share_link_revoked", "space.access_request_created", "space.access_request_resolved", "space.grant_created", "space.grant_updated", "space.grant_revoked", "team.access_defaults_updated", "version.created", "version.ready", "version.warning", "version.failed", "version.expired", "version.canceled", "version.deleted", "version.retention_warning", "version.retention_deleted", "channel.promoted", "build.created", "build.succeeded", "build.failed", "build.canceled", "build.skipped", "domain.created", "domain.verified", "domain.verification_failed", "domain.control_lost", "domain.dns_updated", "domain.nameservers_updated", "domain.registration_purchased", "domain.registration_renewed", "domain.registration_expiring", "domain.registration_expired", "domain.transfer_in_started", "domain.transfer_out_started", "domain.deleted", "domain.attached", "domain.activated", "domain.blocked", "domain.detached", "transfer.requested", "transfer.confirmed", "transfer.completed", "transfer.canceled", "transfer.expired", "transfer.failed", "variable.updated", "variable.deleted", "api_key.created", "api_key.updated", "api_key.revoked", "agent_handoff.created", "agent_handoff.redeemed", "agent_handoff.revoked", "webhook.created", "webhook.updated", "webhook.secret_rotated", "webhook.disabled", "webhook.deleted", "team.updated", "team.slug_updated", "team.member_added", "team.member_removed", "team.member_role_updated", "team.builds_deploys_quota_exceeded", "tenant.past_due", "tenant.suspended", "tenant.reactivated", "tenant.deleted", "export.ready", "export.failed", "import.ready", "import.failed", "comment.token_minted", "comment.created", "comment.reply_created", "comment.archived", "comment.unarchived", "abuse_report.created", "abuse_report.updated", "claim.blocked_takedown", "claim.authority_rotated", "user.created", "user.signed_in", "user.deleted", "user.impersonation_started", "user.impersonation_stopped", "user.two_factor_enabled", "user.two_factor_disabled"];
 export type ActivityEventCode = (typeof ACTIVITY_EVENT_CODES)[number];
 export declare function isActivityEventCode(value: string): value is ActivityEventCode;
 export declare function isValidActivityEventFilter(filter: string): boolean;

package/dist/contracts/activity.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { AnyObjectSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 // The single event taxonomy (internal-docs/platform.md "Event taxonomy").
 // Every emitted activity event and every webhook `events` filter selects on
-// these codes. Growth is additive-only: codes are never renamed or removed.
+// these codes.
 // `appendActivityEvent` is typed against this list, so emitting a code that is
 // not in the table is a typecheck (CI) failure.
 export const ACTIVITY_EVENT_CODES = [
@@ -19,31 +19,22 @@ export const ACTIVITY_EVENT_CODES = [
     "space.deleted",
     "space.config_updated",
     "space.slug_updated",
-    "space.password_updated",
     // site
     "site.provision_requested",
     "site.placement_hold_set",
     "site.placement_hold_cleared",
     "site.burst_toggled",
-    // access (internal-docs/access-plan.html): every access mutation emits an
-    // activity event; operator mints are audited and owner-visible (X-27).
+    // access
     "space.access_logout_all",
     "space.access_transfer_scrub",
-    "space.access_operator_token",
-    "space.sharing_updated",
     "space.share_link_created",
     "space.share_link_revoked",
-    "space.invite_created",
-    "space.invite_revoked",
     "space.access_request_created",
     "space.access_request_resolved",
-    "space.firewall_updated",
+    "space.grant_created",
+    "space.grant_updated",
+    "space.grant_revoked",
     "team.access_defaults_updated",
-    "team.service_token_created",
-    "team.service_token_revoked",
-    "team.access_connection_created",
-    "team.access_connection_updated",
-    "team.access_connection_revoked",
     // version
     "version.created",
     "version.ready",
@@ -135,6 +126,7 @@ export const ACTIVITY_EVENT_CODES = [
     // claim (additive extension: a claim attempt against a taken-down space is
     // flagged, never silently 404ed — internal-docs/platform.md "Abuse Posture")
     "claim.blocked_takedown",
+    "claim.authority_rotated",
     // user (additive extension: account lifecycle plus the 2FA and
     // admin-impersonation effects that must surface through ActivityEvent —
     // internal-docs/platform.md Better Auth usage). `user.created` fires once on
@@ -201,7 +193,11 @@ export const activityQuerySchema = cursorListQuerySchema.extend({
         .describe("Filter to events owned by a team or an external customer principal."),
     principalId: z.string().min(1).optional().describe("Filter to a single principal id."),
     spaceId: z.string().min(1).optional().describe("Filter to events for one space."),
-    code: z.string().min(1).optional().describe("Filter to one event code, e.g. `space.created`."),
+    code: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Filter to one event code, for example `space.created`."),
     since: z.string().datetime().optional().describe("Only events at or after this time."),
     until: z.string().datetime().optional().describe("Only events at or before this time."),
 });

package/dist/contracts/api-keys.d.ts

@@ -5,6 +5,7 @@ export declare const StatticActionSchema: z.ZodEnum<{
     "teams:create": "teams:create";
     "spaces:read": "spaces:read";
     "spaces:write": "spaces:write";
+    "spaces:rename": "spaces:rename";
     "domains:read": "domains:read";
     "mcp:tools": "mcp:tools";
     "*": "*";
@@ -34,6 +35,7 @@ export declare const StatticActionSchema: z.ZodEnum<{
     "webhooks:read": "webhooks:read";
     "webhooks:write": "webhooks:write";
     "builds:read": "builds:read";
+    "builds:trigger": "builds:trigger";
     "builds:create": "builds:create";
     "teams:write": "teams:write";
     "teams:members.write": "teams:members.write";
@@ -87,6 +89,7 @@ export declare const ApiCredentialPolicySchema: z.ZodObject<{
             "teams:create": "teams:create";
             "spaces:read": "spaces:read";
             "spaces:write": "spaces:write";
+            "spaces:rename": "spaces:rename";
             "domains:read": "domains:read";
             "mcp:tools": "mcp:tools";
             "*": "*";
@@ -116,6 +119,7 @@ export declare const ApiCredentialPolicySchema: z.ZodObject<{
             "webhooks:read": "webhooks:read";
             "webhooks:write": "webhooks:write";
             "builds:read": "builds:read";
+            "builds:trigger": "builds:trigger";
             "builds:create": "builds:create";
             "teams:write": "teams:write";
             "teams:members.write": "teams:members.write";
@@ -191,6 +195,7 @@ export declare const ApiKeySchema: z.ZodObject<{
                 "teams:create": "teams:create";
                 "spaces:read": "spaces:read";
                 "spaces:write": "spaces:write";
+                "spaces:rename": "spaces:rename";
                 "domains:read": "domains:read";
                 "mcp:tools": "mcp:tools";
                 "*": "*";
@@ -220,6 +225,7 @@ export declare const ApiKeySchema: z.ZodObject<{
                 "webhooks:read": "webhooks:read";
                 "webhooks:write": "webhooks:write";
                 "builds:read": "builds:read";
+                "builds:trigger": "builds:trigger";
                 "builds:create": "builds:create";
                 "teams:write": "teams:write";
                 "teams:members.write": "teams:members.write";
@@ -303,6 +309,7 @@ export declare const ApiKeyListResponseSchema: z.ZodObject<{
                     "teams:create": "teams:create";
                     "spaces:read": "spaces:read";
                     "spaces:write": "spaces:write";
+                    "spaces:rename": "spaces:rename";
                     "domains:read": "domains:read";
                     "mcp:tools": "mcp:tools";
                     "*": "*";
@@ -332,6 +339,7 @@ export declare const ApiKeyListResponseSchema: z.ZodObject<{
                     "webhooks:read": "webhooks:read";
                     "webhooks:write": "webhooks:write";
                     "builds:read": "builds:read";
+                    "builds:trigger": "builds:trigger";
                     "builds:create": "builds:create";
                     "teams:write": "teams:write";
                     "teams:members.write": "teams:members.write";
@@ -395,6 +403,7 @@ export declare const ApiKeyCreateRequestSchema: z.ZodObject<{
                 "teams:create": "teams:create";
                 "spaces:read": "spaces:read";
                 "spaces:write": "spaces:write";
+                "spaces:rename": "spaces:rename";
                 "domains:read": "domains:read";
                 "mcp:tools": "mcp:tools";
                 "*": "*";
@@ -424,6 +433,7 @@ export declare const ApiKeyCreateRequestSchema: z.ZodObject<{
                 "webhooks:read": "webhooks:read";
                 "webhooks:write": "webhooks:write";
                 "builds:read": "builds:read";
+                "builds:trigger": "builds:trigger";
                 "builds:create": "builds:create";
                 "teams:write": "teams:write";
                 "teams:members.write": "teams:members.write";
@@ -469,6 +479,7 @@ export declare const ApiKeyPatchRequestSchema: z.ZodObject<{
                 "teams:create": "teams:create";
                 "spaces:read": "spaces:read";
                 "spaces:write": "spaces:write";
+                "spaces:rename": "spaces:rename";
                 "domains:read": "domains:read";
                 "mcp:tools": "mcp:tools";
                 "*": "*";
@@ -498,6 +509,7 @@ export declare const ApiKeyPatchRequestSchema: z.ZodObject<{
                 "webhooks:read": "webhooks:read";
                 "webhooks:write": "webhooks:write";
                 "builds:read": "builds:read";
+                "builds:trigger": "builds:trigger";
                 "builds:create": "builds:create";
                 "teams:write": "teams:write";
                 "teams:members.write": "teams:members.write";
@@ -542,6 +554,7 @@ export declare const ApiKeyScopedCreateRequestSchema: z.ZodObject<{
         "teams:create": "teams:create";
         "spaces:read": "spaces:read";
         "spaces:write": "spaces:write";
+        "spaces:rename": "spaces:rename";
         "domains:read": "domains:read";
         "mcp:tools": "mcp:tools";
         "*": "*";
@@ -571,6 +584,7 @@ export declare const ApiKeyScopedCreateRequestSchema: z.ZodObject<{
         "webhooks:read": "webhooks:read";
         "webhooks:write": "webhooks:write";
         "builds:read": "builds:read";
+        "builds:trigger": "builds:trigger";
         "builds:create": "builds:create";
         "teams:write": "teams:write";
         "teams:members.write": "teams:members.write";
@@ -601,6 +615,7 @@ export declare const ApiKeyScopedPatchRequestSchema: z.ZodObject<{
         "teams:create": "teams:create";
         "spaces:read": "spaces:read";
         "spaces:write": "spaces:write";
+        "spaces:rename": "spaces:rename";
         "domains:read": "domains:read";
         "mcp:tools": "mcp:tools";
         "*": "*";
@@ -630,6 +645,7 @@ export declare const ApiKeyScopedPatchRequestSchema: z.ZodObject<{
         "webhooks:read": "webhooks:read";
         "webhooks:write": "webhooks:write";
         "builds:read": "builds:read";
+        "builds:trigger": "builds:trigger";
         "builds:create": "builds:create";
         "teams:write": "teams:write";
         "teams:members.write": "teams:members.write";

package/dist/contracts/api-keys.js

@@ -11,6 +11,7 @@ export const StatticActionSchema = z.enum([
     "spaces:read",
     "spaces:create",
     "spaces:write",
+    "spaces:rename",
     "spaces:delete",
     "spaces:publish",
     "spaces:transfer",
@@ -32,6 +33,7 @@ export const StatticActionSchema = z.enum([
     "webhooks:read",
     "webhooks:write",
     "builds:read",
+    "builds:trigger",
     "builds:create",
     "teams:read",
     "teams:create",
@@ -46,7 +48,7 @@ export const StatticActionSchema = z.enum([
     "runtime:manage",
     "*",
 ]);
-const DescribedStatticActionSchema = StatticActionSchema.describe("A namespaced IAM-lite action (`noun:verb`) or `*` for all actions.");
+const DescribedStatticActionSchema = StatticActionSchema.describe("Namespaced IAM-lite action (`noun:verb`), or `*` for all actions.");
 const RESOURCE_PREFIX = "stt://tenant/";
 function isResourceSegment(value) {
     return Boolean(value && value.length > 0 && !/[\s/\\]/.test(value));
@@ -98,7 +100,7 @@ const StatticResourceSchema = z
     .refine((value) => parseStatticResource(value) !== null, {
     message: "Resource must be a stt:// URI from the StatticResource union (tenant, principal, site, space, site space, domain, or domain-group).",
 })
-    .describe("A resource URI from the StatticResource union: stt://tenant/{t}, …/principal/(team|external)/{id}[/*], …/site/{id}[/*], …/space/{id}[/*], …/site/{id}/space/{id}[/*], …/domain/{id}, or …/domain-group/{id}.");
+    .describe("Resource URI from the resource union: stt://tenant/{t}, …/principal/(team|external)/{id}[/*], …/site/{id}[/*], …/space/{id}[/*], …/site/{id}/space/{id}[/*], …/domain/{id}, or …/domain-group/{id}.");
 export const ApiCredentialPolicySchema = z
     .object({
     version: z
@@ -127,11 +129,11 @@ export const ApiCredentialPolicySchema = z
         })
             .strict()
             .optional()
-            .describe("ANDed condition attributes. Unresolvable attributes fail closed: no-match for allow, match for deny."),
+            .describe("AND condition attributes. Unresolvable attributes fail closed: no match for allow, and match for deny."),
     })
         .strict())
         .min(1)
-        .describe("Evaluation: explicit deny wins, explicit allow permits, otherwise implicit deny."),
+        .describe("Evaluation order: explicit deny wins, explicit allow permits, otherwise implicit deny."),
 })
     .strict()
     .describe("IAM-lite access policy evaluated for every credentialed request.");
@@ -145,12 +147,12 @@ export const ApiKeyPresetSchema = z
     "team_admin",
     "billing_viewer",
 ])
-    .describe("Named policy preset compiled into a concrete access policy at key creation.");
+    .describe("Named policy preset compiled into a concrete access policy when the key is created.");
 // `system` is never a principal type: runtime/internal credentials are
 // platform-owned and omit ownerPrincipal entirely (internal-docs/platform.md).
 const ApiKeyOwnerPrincipalSchema = z.object({
     type: z.enum(["team", "external"]).describe("Principal type that owns this key."),
-    id: z.string().min(1).describe("Stable principal id (Better Auth team id or external id)."),
+    id: z.string().min(1).describe("Stable principal id (Better Auth team id, or external id)."),
 });
 const ApiKeySubjectSchema = z.object({
     type: z
@@ -188,7 +190,7 @@ export const ApiKeyListQuerySchema = cursorListQuerySchema.extend({
         .string()
         .min(1)
         .optional()
-        .describe("Owning team whose keys to list. Defaults to the caller's own team; any team the credential's policy reaches is allowed."),
+        .describe("Owning team whose keys to list. Defaults to the caller's own team. Any team that the credential policy reaches is allowed."),
 });
 export const ApiKeyListResponseSchema = z.object({
     data: z.array(ApiKeySchema),
@@ -200,7 +202,7 @@ export const ApiKeyCreateRequestSchema = z.object({
         .string()
         .min(1)
         .optional()
-        .describe("Owning team for the new key. Defaults to the caller's own team; authorization is by the credential's policy, not key ownership."),
+        .describe("Owning team for the new key. Defaults to the caller's own team. Authorization is by the credential policy, not key ownership."),
     preset: ApiKeyPresetSchema.optional(),
     policy: ApiCredentialPolicySchema.nullable()
         .optional()
@@ -250,7 +252,7 @@ export const ApiKeyScopeSchema = z
     z.object({ kind: z.literal("team"), teamId: z.string().min(1) }).strict(),
     z.object({ kind: z.literal("space"), spaceId: z.string().min(1) }).strict(),
 ])
-    .describe("Explicit, finite policy target. A space scope narrows the derived policy to exactly that space — never the owning team's whole tree.");
+    .describe("Explicit, finite policy target. A space scope narrows the derived policy to exactly that space, never the owning team's whole tree.");
 export const ApiKeyScopedCreateRequestSchema = z
     .object({
     name: z.string().trim().min(1).max(255).optional().describe("Human-readable key name."),

package/dist/contracts/archives.d.ts

@@ -6,8 +6,7 @@ export declare const archiveListQuerySchema: z.ZodObject<{
 export declare const spaceExportRequestSchema: z.ZodObject<{
     versionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     includeFiles: z.ZodDefault<z.ZodBoolean>;
-    includeExplicitConfig: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export declare const spaceExportArchiveSchema: z.ZodObject<{
     contentType: z.ZodLiteral<"application/zip">;
     downloadUrl: z.ZodString;

package/dist/contracts/archives.js

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 import { uploadInstructionsSchema } from "./internal.js";
 export const archiveListQuerySchema = cursorListQuerySchema;
-export const spaceExportRequestSchema = z.object({
+export const spaceExportRequestSchema = z
+    .object({
     versionIds: z
         .array(z.string().min(1))
         .min(1)
@@ -11,12 +12,9 @@ export const spaceExportRequestSchema = z.object({
     includeFiles: z
         .boolean()
         .default(true)
-        .describe("Include version file trees and compiled serving artifacts. `false` produces a config-only archive that is not self-servable and cannot be re-imported."),
-    includeExplicitConfig: z
-        .boolean()
-        .default(true)
-        .describe("Include explicit space config (the space access policy) in the archive. Version manifests are always included."),
-});
+        .describe("Pass `true` to include version file trees and compiled serving artifacts. Pass `false` for a config-only archive that is not self-servable and cannot be re-imported."),
+})
+    .strict();
 export const spaceExportArchiveSchema = z.object({
     // Zip-only contract: spacefast_export_v1 archives are always zip (the spec
     // allows "zip or tar"; one format keeps the enum honest).
@@ -35,8 +33,8 @@ export const spaceExportArchiveSchema = z.object({
         .describe("SHA-256 of the archive bytes (64 lowercase hex characters), for verification."),
 });
 export const spaceExportSchema = z.object({
-    id: z.string().describe("Export handle id (exp_…)."),
-    spaceId: z.string().describe("Source space id (spc_…)."),
+    id: z.string().describe("The export handle id (`exp_…`)."),
+    spaceId: z.string().describe("The source space id (`spc_…`)."),
     status: z
         .enum(["queued", "running", "ready", "failed", "expired"])
         .describe("Export lifecycle. `expired` means the archive download window has passed."),
@@ -54,8 +52,8 @@ export const spaceExportSchema = z.object({
         .string()
         .nullable()
         .describe("Operation (op_…) tracking the asynchronous export work."),
-    createdAt: z.string().datetime().describe("When the export handle was created."),
-    updatedAt: z.string().datetime().describe("When the export handle last changed."),
+    createdAt: z.string().datetime().describe("Instant when the export handle was created."),
+    updatedAt: z.string().datetime().describe("Instant when the export handle last changed."),
 });
 export const spaceExportListResponseSchema = z.object({
     data: z.array(spaceExportSchema),
@@ -83,11 +81,11 @@ export const spaceImportRequestSchema = z.object({
     publish: z
         .boolean()
         .default(false)
-        .describe("Promote the newest imported version to the live channel once materialized. Imported versions never go public implicitly."),
+        .describe("Pass `true` to promote the newest imported version to the live channel after it materializes. Imported versions never go public implicitly."),
 });
 export const spaceImportSchema = z.object({
-    id: z.string().describe("Import handle id (imp_…)."),
-    targetSpaceId: z.string().describe("Target space id (spc_…) the import materializes into."),
+    id: z.string().describe("The import handle id (`imp_…`)."),
+    targetSpaceId: z.string().describe("The target space id (`spc_…`) the import materializes into."),
     status: z
         .enum([
         "created",
@@ -101,7 +99,7 @@ export const spaceImportSchema = z.object({
         .describe("Import lifecycle. Upload-kind imports wait in `waiting_for_archive` until the archive is uploaded and the import is finalized."),
     archiveUpload: uploadInstructionsSchema
         .optional()
-        .describe("Archive upload instructions — the same upload contract as publish. Present while status is `waiting_for_archive`: PUT the archive to `{baseUrl}/{files[0]}` with the session token, then POST `links.finalize`. Each fetch of the import re-mints a fresh token."),
+        .describe("Archive upload instructions. This is the same upload contract as publish. Present while status is `waiting_for_archive`: PUT the archive to `{baseUrl}/{files[0]}` with the session token, then POST `links.finalize`. Each fetch of the import mints a fresh token."),
     draftVersionIds: z
         .array(z.string())
         .describe("Version ids (ver_…) minted and owned by this import."),
@@ -113,8 +111,8 @@ export const spaceImportSchema = z.object({
         .string()
         .nullable()
         .describe("Operation (op_…) tracking the asynchronous import work."),
-    createdAt: z.string().datetime().describe("When the import handle was created."),
-    updatedAt: z.string().datetime().describe("When the import handle last changed."),
+    createdAt: z.string().datetime().describe("Instant when the import handle was created."),
+    updatedAt: z.string().datetime().describe("Instant when the import handle last changed."),
 });
 export const spaceImportListResponseSchema = z.object({
     data: z.array(spaceImportSchema),

package/dist/contracts/beta.js

@@ -91,7 +91,7 @@ export const SuperadminBetaSignupSchema = z.object({
     invitedBy: z
         .string()
         .nullable()
-        .describe("Inviting operator's user id; null = auto-approved (Automattician signup)."),
+        .describe("Inviting operator user id; null when auto-approved (Automattician signup)."),
     enrolledUserId: z.string().nullable(),
     createdAt: z.string().datetime(),
 });

package/dist/contracts/builds.js

@@ -27,7 +27,7 @@ export const BuildSettingsSchema = z
     allowUnsupportedPlatformFeatures: z.boolean().default(false),
     timeoutSeconds: buildTimeoutSecondsSchema,
 })
-    .describe("Resolved build settings. Builds persist this as an immutable settingsSnapshot.");
+    .describe("Resolved build settings. Builds persist this as an immutable `settingsSnapshot`.");
 export const BuildTargetSchema = z
     .object({
     channel: z
@@ -39,7 +39,7 @@ export const BuildTargetSchema = z
         .describe("Channel to promote when the build succeeds; null means no automatic promotion."),
     preview: z.boolean().default(false).describe("Whether the build targets preview behavior."),
 })
-    .describe("Where a successful build should publish or preview.");
+    .describe("Where a successful build should publish or run in preview mode.");
 // Shared by InternalBuildSourceSchema and InternalBuildInputSchema: both carry
 // this exact archive-source member in their `kind` discriminated union.
 const internalArchiveBuildSourceSchema = z.object({
@@ -48,7 +48,7 @@ const internalArchiveBuildSourceSchema = z.object({
     sourceMetadata: z
         .record(z.string(), z.unknown())
         .optional()
-        .describe("Internal source provenance copied to the produced Version."),
+        .describe("Internal source provenance copied to the produced version."),
     objectKey: z.string().optional().describe("Internal staged archive object key."),
     uploadedAt: z.string().datetime().optional().describe("When the archive finished staging."),
     recoveredAt: z
@@ -76,7 +76,7 @@ const InternalBuildSourceSchema = z
     }),
     internalArchiveBuildSourceSchema,
 ])
-    .describe("Legacy internal build source shape retained while build routes migrate to input.");
+    .describe("Legacy internal build source shape, retained while build routes migrate to input.");
 const InternalBuildInputSchema = z
     .discriminatedUnion("kind", [
     internalArchiveBuildSourceSchema,
@@ -126,7 +126,7 @@ export const PublicBuildInputSchema = z
     })
         .strict(),
 ])
-    .describe("Public build input. Internal clone URLs and staged object keys are not exposed.");
+    .describe("Public build input. Internal clone URLs and staged object keys are hidden.");
 export const BuildCreateInputSchema = z
     .discriminatedUnion("kind", [
     z
@@ -135,7 +135,7 @@ export const BuildCreateInputSchema = z
         sourceMetadata: z
             .record(z.string(), z.unknown())
             .optional()
-            .describe("Optional source provenance for the produced Version."),
+            .describe("Optional source provenance for the produced version."),
     })
         .strict(),
     z.object({
@@ -153,7 +153,7 @@ export const BuildCreateInputSchema = z
 // plain string here since the runner's specific phase vocabulary is an
 // app-level concern, not a shared contract.
 const buildExecutionPhaseSchema = z.object({
-    phase: z.string().min(1).describe("Build phase name; see BUILD_PHASES in builds/runner.ts."),
+    phase: z.string().min(1).describe("Build phase name. See `BUILD_PHASES` in `builds/runner.ts`."),
     at: z.string().datetime(),
 });
 const buildExecutionLaunchSchema = z.object({
@@ -188,11 +188,11 @@ const InternalBuildExecutionSchema = z
     phases: z
         .array(buildExecutionPhaseSchema)
         .optional()
-        .describe("Phase timeline the runner appends to via recordBuildPhase."),
+        .describe("Phase timeline that the runner appends to with `recordBuildPhase`."),
 })
     .describe("Internal runner execution metadata surfaced only where appropriate.");
 export const BuildSchema = z.object({
-    id: z.string().describe("Build id (`bld_`); opaque, never derived from a version id."),
+    id: z.string().describe("Build id (`bld_`); opaque and never derived from a version id."),
     spaceId: z.string().describe("Space (`spc_`) the build produces a version for."),
     status: buildStatus.describe("Build lifecycle status."),
     input: PublicBuildInputSchema,
@@ -206,12 +206,12 @@ export const BuildSchema = z.object({
     producedVersionId: z
         .string()
         .nullable()
-        .describe("Version (`ver_`) minted by a succeeded build; null otherwise."),
+        .describe("Version (`ver_`) minted by a successful build; null otherwise."),
     reusedVersionId: z
         .string()
         .nullable()
         .default(null)
-        .describe("Existing version reused by a succeeded no-change build; null otherwise."),
+        .describe("Existing version reused by a successful no-change build; null otherwise."),
     diagnostics: z.array(baseDiagnosticSchema).default([]),
     createdAt: z.string().datetime(),
     startedAt: z.string().datetime().nullable().describe("When the runner picked the build up."),
@@ -221,7 +221,7 @@ export const buildCreateRequestSchema = z.object({
     input: BuildCreateInputSchema,
     settings: BuildSettingsSchema.partial()
         .optional()
-        .describe("Per-run settings overrides; persisted as settingsSnapshot after resolution."),
+        .describe("Per-run settings overrides, persisted as `settingsSnapshot` after resolution."),
     target: BuildTargetSchema.partial().optional(),
     diagnostics: z
         .array(baseDiagnosticSchema)
@@ -253,9 +253,9 @@ export const spaceBuildIntegrationSchema = z
     .object({
     branchChannels: z
         .record(z.string().min(1).describe("Git branch or ref name."), z.literal("live").describe("Channel the branch's builds promote to."))
-        .describe("Exact branch/ref name to channel name, e.g. { main: 'live' }."),
+        .describe("Exact branch or ref name to channel name, for example `{ main: 'live' }`."),
 })
-    .describe("Per-space build integration config: where repository builds promote.");
+    .describe("Per-space build integration config that defines where repository builds promote.");
 /** Channel a repository build promotes to, or null when the ref is unmapped (default channel applies). */
 export function resolveBuildChannel(integration, ref) {
     return integration?.branchChannels[ref] ?? null;

package/dist/contracts/channels.js

@@ -21,7 +21,7 @@ export const channelListItemSchema = z.object({
         .nullable()
         .optional()
         .describe("Last version this channel served before the current pointer (rollback target)."),
-    updatedAt: z.string().datetime().describe("When this channel pointer last moved."),
+    updatedAt: z.string().datetime().describe("Instant when this channel pointer last moved."),
 });
 // One entry of a channel's promotion history (the deploy log): a single
 // `channel.promoted` event, newest first. This is the audit trail of every
@@ -40,7 +40,7 @@ export const channelHistoryEntrySchema = z.object({
         .optional()
         .describe("Kind of actor that performed the promotion."),
     actorId: z.string().nullable().optional().describe("Identifier of the promoting actor."),
-    at: z.string().datetime().describe("When the promotion happened."),
+    at: z.string().datetime().describe("Instant when the promotion happened."),
 });
 export const channelListResponseSchema = z.object({
     data: z.array(channelListItemSchema),