@siglume/api-sdk 0.10.0 → 0.10.2

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript runtime for building, testing, and registering Siglume developer apps.
 
-This package is prepared in the public SDK repo and ships with the current v0.7.6 release line.
+This package is prepared in the public SDK repo and ships with the current v0.10.x release line.
 
 It also includes `draft_tool_manual()` and `fill_tool_manual_gaps()` with
 bundled `AnthropicProvider` and `OpenAIProvider` classes. Provide
@@ -65,8 +65,8 @@ siglume score . --offline
 siglume validate .
 siglume score . --remote
 siglume preflight .         # checks blockers without creating a draft
-siglume register .            # preflight + draft only
-siglume register . --confirm # confirm + publish
+siglume register .          # preflight + auto-register + confirm/publish
+siglume register . --draft-only # review-only draft staging
 ```
 
 `siglume register` reads `tool_manual.json`, the local Git-ignored
@@ -76,8 +76,9 @@ credential files Git-ignored because they can contain review keys and client
 secrets. SDK / HTTP automation can pass
 `source_url`, `source_context`, and `input_form_spec` directly to
 `auto-register`. The CLI runs preflight by default, then calls the same
-`auto-register` route used by SDK / automation clients. Re-run the
-same `capability_key` to stage an upgrade. The server-side publish gate
+`auto-register` route used by SDK / automation clients and confirms publication
+unless `--draft-only` is set. Re-run the same `capability_key` to publish a
+non-material upgrade when checks pass. The server-side publish gate
 includes runtime checks, contract checks, seller OAuth checks, pricing / payout
 rules, and a mandatory fail-closed LLM legal review for law compliance plus
 public-order / morals compliance.

package/dist/bin/siglume.cjs

@@ -140,18 +140,6 @@ function camelCaseFromCapabilityKey(capabilityKey) {
   }
   return `${words.map((word) => word[0].toUpperCase() + word.slice(1)).join("")}App`;
 }
-function buildDefaultI18n(manifestPayload) {
-  const job = String(manifestPayload.job_to_be_done ?? "").trim();
-  const shortDescription = String(
-    manifestPayload.short_description ?? manifestPayload.job_to_be_done ?? manifestPayload.name ?? ""
-  ).trim();
-  return {
-    job_to_be_done_en: job,
-    job_to_be_done_ja: job,
-    short_description_en: shortDescription,
-    short_description_ja: shortDescription
-  };
-}
 function buildRegistrationStubSource(manifestPayload, toolManualPayload) {
   const capabilityKey = String(manifestPayload.capability_key ?? "generated-registration");
   const jobToBeDone = String(
@@ -306,10 +294,8 @@ var init_webhooks = __esm({
       "subscription.cancelled",
       "subscription.paused",
       "subscription.reinstated",
-      "refund.issued",
       "payment.succeeded",
       "payment.failed",
-      "payment.disputed",
       "capability.published",
       "capability.delisted",
       "execution.completed",
@@ -1349,6 +1335,7 @@ function parseListing(data) {
     price_value_minor: Number(data.price_value_minor ?? 0),
     currency: String(data.currency ?? "USD"),
     short_description: stringOrNull(data.short_description),
+    description: stringOrNull(data.description),
     docs_url: stringOrNull(data.docs_url),
     support_contact: stringOrNull(data.support_contact),
     seller_display_name: stringOrNull(data.seller_display_name),
@@ -1373,19 +1360,6 @@ function parseBundleMember(data) {
     link_id: stringOrNull(data.link_id)
   };
 }
-function parseConnectedAccountProvider(data) {
-  return {
-    provider_key: String(data.provider_key ?? ""),
-    display_name: String(data.display_name ?? ""),
-    auth_type: String(data.auth_type ?? "oauth2"),
-    refresh_supported: Boolean(data.refresh_supported ?? false),
-    pkce_required: Boolean(data.pkce_required ?? false),
-    default_scopes: Array.isArray(data.default_scopes) ? data.default_scopes.filter((s) => typeof s === "string") : [],
-    available_scopes: Array.isArray(data.available_scopes) ? data.available_scopes.filter((s) => typeof s === "string") : [],
-    scope_separator: String(data.scope_separator ?? " "),
-    notes: stringOrNull(data.notes)
-  };
-}
 function parseConnectedAccountLifecycle(data) {
   return {
     connected_account_id: String(data.connected_account_id ?? ""),
@@ -2427,50 +2401,6 @@ function parseMarketProposalActionResult(execution) {
     raw: { ...execution.raw }
   };
 }
-function parseRefund(data) {
-  return {
-    refund_id: String(data.refund_id ?? data.id ?? ""),
-    receipt_id: String(data.receipt_id ?? ""),
-    owner_user_id: stringOrNull(data.owner_user_id) ?? void 0,
-    payment_mandate_id: stringOrNull(data.payment_mandate_id) ?? void 0,
-    usage_event_id: stringOrNull(data.usage_event_id) ?? void 0,
-    chain_receipt_id: stringOrNull(data.chain_receipt_id) ?? void 0,
-    amount_minor: Number(data.amount_minor ?? 0),
-    currency: String(data.currency ?? "USD"),
-    status: String(data.status ?? "issued"),
-    reason_code: String(data.reason_code ?? "customer-request"),
-    note: stringOrNull(data.note) ?? void 0,
-    idempotency_key: stringOrNull(data.idempotency_key) ?? void 0,
-    on_chain_tx_hash: stringOrNull(data.on_chain_tx_hash) ?? void 0,
-    metadata: toRecord(data.metadata),
-    idempotent_replay: Boolean(data.idempotent_replay ?? false),
-    created_at: stringOrNull(data.created_at) ?? void 0,
-    updated_at: stringOrNull(data.updated_at) ?? void 0,
-    raw: { ...data }
-  };
-}
-function parseDispute(data) {
-  return {
-    dispute_id: String(data.dispute_id ?? data.id ?? ""),
-    receipt_id: String(data.receipt_id ?? ""),
-    owner_user_id: stringOrNull(data.owner_user_id) ?? void 0,
-    payment_mandate_id: stringOrNull(data.payment_mandate_id) ?? void 0,
-    usage_event_id: stringOrNull(data.usage_event_id) ?? void 0,
-    external_dispute_id: stringOrNull(data.external_dispute_id) ?? void 0,
-    status: String(data.status ?? "open"),
-    reason_code: String(data.reason_code ?? "manual-review"),
-    description: stringOrNull(data.description) ?? void 0,
-    evidence: toRecord(data.evidence),
-    response_decision: stringOrNull(data.response_decision) ?? void 0,
-    response_note: stringOrNull(data.response_note) ?? void 0,
-    responded_at: stringOrNull(data.responded_at) ?? void 0,
-    metadata: toRecord(data.metadata),
-    idempotent_replay: Boolean(data.idempotent_replay ?? false),
-    created_at: stringOrNull(data.created_at) ?? void 0,
-    updated_at: stringOrNull(data.updated_at) ?? void 0,
-    raw: { ...data }
-  };
-}
 function cloneJsonLike(value) {
   if (Array.isArray(value)) {
     return value.map((item) => cloneJsonLike(item));
@@ -2555,10 +2485,13 @@ var init_client = __esm({
       async auto_register(manifest, tool_manual, options = {}) {
         const manifestPayload = coerceMapping(manifest, "manifest");
         const toolManualPayload = coerceMapping(tool_manual, "tool_manual");
+        const toolManualForRequest = { ...toolManualPayload };
+        const embeddedInputFormSpec = toolManualForRequest.input_form_spec;
+        delete toolManualForRequest.input_form_spec;
+        const inputFormSpec = options.input_form_spec ?? embeddedInputFormSpec;
         const payload = {
-          i18n: buildDefaultI18n(manifestPayload),
           manifest: { ...manifestPayload },
-          tool_manual: { ...toolManualPayload }
+          tool_manual: toolManualForRequest
         };
         if (options.source_url) {
           payload.source_url = options.source_url;
@@ -2577,14 +2510,11 @@ var init_client = __esm({
             )
           } : coerceMapping(options.oauth_credentials, "oauth_credentials");
         }
-        if (options.metadata) {
-          payload.metadata = coerceMapping(options.metadata, "metadata");
-        }
         if (options.source_context) {
           payload.source_context = coerceMapping(options.source_context, "source_context");
         }
-        if (options.input_form_spec) {
-          payload.input_form_spec = coerceMapping(options.input_form_spec, "input_form_spec");
+        if (inputFormSpec !== void 0 && inputFormSpec !== null) {
+          payload.input_form_spec = coerceMapping(inputFormSpec, "input_form_spec");
         }
         for (const fieldName of [
           "capability_key",
@@ -2635,7 +2565,11 @@ var init_client = __esm({
         if (!listing_id) {
           throw new SiglumeClientError("Siglume auto-register response did not include listing_id.");
         }
-        this.pendingConfirmations.set(listing_id, { manifest: manifestPayload, tool_manual: toolManualPayload });
+        this.pendingConfirmations.set(listing_id, {
+          manifest: manifestPayload,
+          tool_manual: toRecord(payload.tool_manual),
+          input_form_spec: toRecord(payload.input_form_spec)
+        });
         return {
           listing_id,
           status: String(data.status ?? "draft"),
@@ -2783,11 +2717,6 @@ var init_client = __esm({
       // ----- end bundles -------------------------------------------------------
       // ----- Connected accounts (v0.7 track 3) ---------------------------------
       // `resolve()` is intentionally NOT wrapped: runtime-only, never over the wire.
-      async list_connected_account_providers() {
-        const [data] = await this.request("GET", "/me/connected-accounts/providers");
-        const items = Array.isArray(data.items) ? data.items : [];
-        return items.filter((item) => isRecord(item)).map(parseConnectedAccountProvider);
-      }
       async start_connected_account_oauth(input) {
         const body = {
           listing_id: input.listing_id,
@@ -2824,8 +2753,17 @@ var init_client = __esm({
         const body = {
           provider_key: input.provider_key,
           client_id: input.client_id,
-          client_secret: input.client_secret
+          client_secret: input.client_secret,
+          authorize_url: input.authorize_url,
+          token_url: input.token_url
         };
+        if (input.revoke_url !== void 0) body.revoke_url = input.revoke_url;
+        if (input.display_name !== void 0) body.display_name = input.display_name;
+        if (input.scope_separator !== void 0) body.scope_separator = input.scope_separator;
+        if (input.token_endpoint_auth !== void 0) body.token_endpoint_auth = input.token_endpoint_auth;
+        if (input.pkce_required !== void 0) body.pkce_required = input.pkce_required;
+        if (input.refresh_supported !== void 0) body.refresh_supported = input.refresh_supported;
+        if (input.available_scopes !== void 0) body.available_scopes = input.available_scopes;
         if (input.required_scopes !== void 0) body.required_scopes = input.required_scopes;
         const [data] = await this.request("PUT", `/market/capabilities/${listing_id}/oauth-credentials`, {
           json_body: body
@@ -4230,105 +4168,6 @@ ${details}` : summary;
           fetchNext: next_cursor ? (cursor) => this.list_support_cases({ ...options, cursor }) : void 0
         });
       }
-      async issue_partial_refund(options) {
-        const receipt_id = String(options.receipt_id ?? "").trim();
-        const idempotency_key = String(options.idempotency_key ?? "").trim();
-        if (!receipt_id) {
-          throw new SiglumeClientError("receipt_id is required.");
-        }
-        if (!idempotency_key) {
-          throw new SiglumeClientError("idempotency_key is required.");
-        }
-        if (!Number.isFinite(options.amount_minor)) {
-          throw new SiglumeClientError("amount_minor must be a finite number.");
-        }
-        const amount_minor = Math.trunc(options.amount_minor);
-        if (amount_minor <= 0) {
-          throw new SiglumeClientError("amount_minor must be positive.");
-        }
-        if (typeof options.original_amount_minor === "number" && amount_minor > Math.trunc(options.original_amount_minor)) {
-          throw new SiglumeClientError("amount_minor cannot exceed the original receipt amount.");
-        }
-        const [data] = await this.request("POST", "/market/refunds", {
-          json_body: {
-            receipt_id,
-            amount_minor,
-            reason_code: options.reason ?? "customer-request",
-            note: options.note,
-            idempotency_key
-          }
-        });
-        return parseRefund(data);
-      }
-      async issue_full_refund(options) {
-        const receipt_id = String(options.receipt_id ?? "").trim();
-        if (!receipt_id) {
-          throw new SiglumeClientError("receipt_id is required.");
-        }
-        const provided_key = String(options.idempotency_key ?? "").trim();
-        const idempotency_key = provided_key || `full-refund:${receipt_id}`;
-        const [data] = await this.request("POST", "/market/refunds", {
-          json_body: {
-            receipt_id,
-            reason_code: options.reason ?? "customer-request",
-            note: options.note,
-            idempotency_key
-          }
-        });
-        return parseRefund(data);
-      }
-      async list_refunds(options = {}) {
-        const [data] = await this.requestAny("GET", "/market/refunds", {
-          params: {
-            receipt_id: options.receipt_id,
-            limit: Math.max(1, Math.min(Math.trunc(options.limit ?? 50), 100))
-          }
-        });
-        if (!Array.isArray(data)) {
-          throw new SiglumeClientError("Expected refunds to be returned as an array.");
-        }
-        return data.filter((item) => isRecord(item)).map(parseRefund);
-      }
-      async get_refund(refund_id) {
-        const [data] = await this.request("GET", `/market/refunds/${refund_id}`);
-        return parseRefund(data);
-      }
-      async get_refunds_for_receipt(receipt_id, options = {}) {
-        return this.list_refunds({ receipt_id, limit: options.limit });
-      }
-      async list_disputes(options = {}) {
-        const [data] = await this.requestAny("GET", "/market/disputes", {
-          params: {
-            receipt_id: options.receipt_id,
-            limit: Math.max(1, Math.min(Math.trunc(options.limit ?? 50), 100))
-          }
-        });
-        if (!Array.isArray(data)) {
-          throw new SiglumeClientError("Expected disputes to be returned as an array.");
-        }
-        return data.filter((item) => isRecord(item)).map(parseDispute);
-      }
-      async get_dispute(dispute_id) {
-        const [data] = await this.request("GET", `/market/disputes/${dispute_id}`);
-        return parseDispute(data);
-      }
-      async respond_to_dispute(options) {
-        const dispute_id = String(options.dispute_id ?? "").trim();
-        if (!dispute_id) {
-          throw new SiglumeClientError("dispute_id is required.");
-        }
-        if (!isRecord(options.evidence)) {
-          throw new SiglumeClientError("evidence must be an object.");
-        }
-        const [data] = await this.request("POST", `/market/disputes/${dispute_id}/respond`, {
-          json_body: {
-            response: options.response,
-            evidence: toRecord(options.evidence),
-            note: options.note
-          }
-        });
-        return parseDispute(data);
-      }
       async create_webhook_subscription(options) {
         const normalizedEventTypes = options.event_types.map((item) => String(item).trim()).filter((item) => item.length > 0);
         if (normalizedEventTypes.length === 0) {
@@ -5837,16 +5676,24 @@ function coerceToolManual(manual) {
 }
 function checkSchemaForbiddenRecursive(schema, rootField, pushIssue, path = "") {
   for (const keyword of COMPOSITION_KEYWORDS) {
-    if (keyword in schema) {
-      const location = path ? `${rootField}.${path}.${keyword}` : `${rootField}.${keyword}`;
-      pushIssue(
-        issue(
-          "INPUT_SCHEMA",
-          `Composition keyword '${keyword}' is not allowed in beta${path ? ` at ${path}` : ""}`,
-          location
-        )
-      );
+    if (!(keyword in schema)) {
+      continue;
+    }
+    const branches = schema[keyword];
+    const location = path ? `${rootField}.${path}.${keyword}` : `${rootField}.${keyword}`;
+    if (!Array.isArray(branches) || branches.length === 0) {
+      pushIssue(issue("INPUT_SCHEMA", `${keyword} must be a non-empty array`, location));
+      continue;
     }
+    branches.forEach((branch, index) => {
+      const branchPath = path ? `${path}.${keyword}[${index}]` : `${keyword}[${index}]`;
+      const branchLocation = `${rootField}.${branchPath}`;
+      if (!isRecord(branch)) {
+        pushIssue(issue("INPUT_SCHEMA", `${keyword}[${index}] must be an object`, branchLocation));
+        return;
+      }
+      checkSchemaForbiddenRecursive(branch, rootField, pushIssue, branchPath);
+    });
   }
   for (const forbidden of INPUT_SCHEMA_FORBIDDEN_KEYS) {
     if (forbidden in schema) {
@@ -7213,43 +7060,51 @@ async function loadProject(path = ".") {
     oauth_credentials
   };
 }
-var OAUTH_PROVIDER_ALIASES = {
-  x: "twitter",
-  "x-twitter": "twitter",
-  twitter: "twitter",
-  slack: "slack",
-  google: "google",
-  gmail: "google",
-  "google-drive": "google",
-  "google-calendar": "google",
-  github: "github",
-  linear: "linear",
-  notion: "notion"
-};
+function isPlatformManagedRequirement(value) {
+  if (!isRecord(value)) return false;
+  if (value.platform_managed === true) return true;
+  const owner = String(
+    value.managed_by ?? value.auth_managed_by ?? value.connection_owner ?? ""
+  ).trim().toLowerCase().replaceAll("_", "-");
+  return owner === "platform" || owner === "siglume" || owner === "siglume-platform";
+}
 function oauthProviderKeyFromRequirement(value) {
-  const raw = String(value ?? "").trim().toLowerCase().replaceAll("_", "-");
-  if (!raw) return null;
-  if (OAUTH_PROVIDER_ALIASES[raw]) {
-    return OAUTH_PROVIDER_ALIASES[raw];
-  }
-  for (const token of raw.replaceAll("/", "-").replaceAll(":", "-").split("-")) {
-    const next = token.trim();
-    if (OAUTH_PROVIDER_ALIASES[next]) {
-      return OAUTH_PROVIDER_ALIASES[next];
+  if (isRecord(value)) {
+    for (const key of ["provider_key", "provider", "account_type", "name"]) {
+      const providerKey = oauthProviderKeyFromRequirement(value[key]);
+      if (providerKey) return providerKey;
     }
+    return null;
   }
-  return null;
+  const raw = String(value ?? "").trim();
+  return raw || null;
 }
 function requiredOauthProviders(requirements) {
   const providers = [];
   for (const item of requirements ?? []) {
+    if (!isPlatformManagedRequirement(item)) continue;
     const providerKey = oauthProviderKeyFromRequirement(item);
+    if (!providerKey) {
+      throw new SiglumeProjectError(
+        "required_connected_accounts platform-managed entries must include a provider_key"
+      );
+    }
     if (providerKey && !providers.includes(providerKey)) {
       providers.push(providerKey);
     }
   }
   return providers;
 }
+function connectedAccountRequirementLabel(value) {
+  if (isRecord(value)) {
+    for (const key of ["provider_key", "provider", "account_type", "name"]) {
+      const label = String(value[key] ?? "").trim();
+      if (label) return label;
+    }
+    return "";
+  }
+  return String(value ?? "").trim();
+}
 function oauthProviderRecordsMap(payload) {
   if (!payload) {
     return {};
@@ -7262,7 +7117,23 @@ function oauthProviderRecordsMap(payload) {
     }
     const providerKey = oauthProviderKeyFromRequirement(item.provider_key ?? item.provider);
     if (!providerKey) {
-      throw new SiglumeProjectError(`oauth_credentials[${index}].provider_key is unsupported.`);
+      throw new SiglumeProjectError(`oauth_credentials[${index}].provider_key is required.`);
+    }
+    const authorizeUrl = String(item.authorize_url ?? item.authorization_url ?? item.auth_url ?? "").trim();
+    const tokenUrl = String(item.token_url ?? "").trim();
+    if (!authorizeUrl || !tokenUrl) {
+      throw new SiglumeProjectError(
+        `oauth_credentials[${index}] must include authorize_url and token_url.`
+      );
+    }
+    for (const [urlKey, urlValue] of Object.entries({
+      authorize_url: authorizeUrl,
+      token_url: tokenUrl,
+      revoke_url: String(item.revoke_url ?? "").trim()
+    })) {
+      if (urlValue && !urlValue.startsWith("https://")) {
+        throw new SiglumeProjectError(`oauth_credentials[${index}].${urlKey} must be an https URL.`);
+      }
     }
     const clientId = String(item.client_id ?? "").trim();
     const clientSecret = String(item.client_secret ?? "").trim();
@@ -7278,12 +7149,30 @@ function oauthProviderRecordsMap(payload) {
     } else {
       scopes = rawScopes.map((scope) => String(scope ?? "").trim()).filter(Boolean);
     }
-    resolved[providerKey] = {
+    const record = {
       provider_key: providerKey,
       client_id: clientId,
       client_secret: clientSecret,
       required_scopes: scopes
     };
+    for (const [key, value] of Object.entries({
+      authorize_url: authorizeUrl,
+      token_url: tokenUrl,
+      revoke_url: String(item.revoke_url ?? "").trim(),
+      display_name: String(item.display_name ?? "").trim(),
+      scope_separator: String(item.scope_separator ?? "").trim(),
+      token_endpoint_auth: String(item.token_endpoint_auth ?? "").trim()
+    })) {
+      if (value) record[key] = value;
+    }
+    for (const key of ["pkce_required", "refresh_supported"]) {
+      if (typeof item[key] === "boolean") record[key] = item[key];
+    }
+    if (Array.isArray(item.available_scopes)) {
+      const availableScopes = item.available_scopes.map((scope) => String(scope ?? "").trim()).filter(Boolean);
+      if (availableScopes.length > 0) record.available_scopes = availableScopes;
+    }
+    resolved[providerKey] = record;
   }
   return resolved;
 }
@@ -7309,7 +7198,7 @@ function ensureRequiredOauthCredentials(project) {
   }
   const path = project.oauth_credentials_path ?? (0, import_node_path.join)(project.root_dir, "oauth_credentials.json");
   throw new SiglumeProjectError(
-    `${path} is required for OAuth-backed APIs. Missing provider seeds: ${missing.join(", ")}`
+    `${path} is required for platform-managed OAuth APIs. Missing provider seeds: ${missing.join(", ")}`
   );
 }
 async function validateProject(path = ".", deps = {}) {
@@ -7477,7 +7366,7 @@ async function registrationPreflight(project, client) {
     errors.push(`remote Tool Manual quality is not publishable: ${remoteQuality.grade} (${remoteQuality.overall_score}/100)`);
   }
   if (missingOauthProviders.length > 0) {
-    errors.push(`oauth_credentials.json is required for OAuth-backed APIs: ${missingOauthProviders.join(", ")}`);
+    errors.push(`oauth_credentials.json is required for platform-managed OAuth APIs: ${missingOauthProviders.join(", ")}`);
   }
   const preflight = {
     manifest_issues: manifestIssues,
@@ -7503,6 +7392,7 @@ async function runRegistration(path = ".", options = {}, deps = {}) {
   ensureManifestPublisherIdentity(project);
   ensureRuntimeValidationReady(project);
   ensureRequiredOauthCredentials(project);
+  const canonicalOauthCredentials = canonicalOauthCredentialsPayload(project.oauth_credentials);
   const client = await createClient(deps);
   const preflight = await registrationPreflight(project, client);
   let developerPortalPreflight = null;
@@ -7518,7 +7408,7 @@ async function runRegistration(path = ".", options = {}, deps = {}) {
   }
   const receipt = await client.auto_register(project.manifest, project.tool_manual, {
     runtime_validation: project.runtime_validation,
-    oauth_credentials: canonicalOauthCredentialsPayload(project.oauth_credentials)
+    oauth_credentials: canonicalOauthCredentials
   });
   const result = {
     receipt: toJsonable(receipt),
@@ -7529,7 +7419,8 @@ async function runRegistration(path = ".", options = {}, deps = {}) {
   if (developerPortalPreflight) {
     result.developer_portal_preflight = developerPortalPreflight;
   }
-  if (options.confirm) {
+  const shouldConfirm = Boolean(options.confirm) || options.confirm === void 0 && !options.draft_only && !options.submit_review;
+  if (shouldConfirm) {
     result.confirmation = toJsonable(await client.confirm_registration(receipt.listing_id));
     if (options.submit_review) {
       result.submit_review_skipped = true;
@@ -8060,8 +7951,8 @@ function operationReadmeTemplate(operation, manifest, warning) {
     "siglume score . --remote",
     "siglume preflight .",
     "siglume register .",
-    "# inspect the draft, then explicitly approve publish:",
-    "siglume register . --confirm",
+    "# review-only staging path:",
+    "siglume register . --draft-only",
     "```",
     ""
   ].join("\n");
@@ -8072,7 +7963,7 @@ function apiUsageDocsTemplate(manifest) {
   const jobToBeDone = String(manifest.job_to_be_done ?? "Describe what this API lets an agent do.");
   const permissionClass = String(manifest.permission_class ?? "read-only");
   const priceModel = String(manifest.price_model ?? "free");
-  const requiredAccounts = (manifest.required_connected_accounts ?? []).join(", ") || "none";
+  const requiredAccounts = (manifest.required_connected_accounts ?? []).map((item) => connectedAccountRequirementLabel(item)).filter(Boolean).join(", ") || "none";
   const supportContact = String(manifest.support_contact ?? "replace-with-support-contact");
   return [
     `# ${name} API Usage Guide`,
@@ -8633,8 +8524,8 @@ function readmeTemplate(template) {
     "siglume score . --remote",
     "siglume preflight .",
     "siglume register .",
-    "# inspect the draft, then explicitly approve publish:",
-    "siglume register . --confirm",
+    "# review-only staging path:",
+    "siglume register . --draft-only",
     "```",
     ""
   ].join("\n");
@@ -8816,16 +8707,25 @@ async function runCli(argv, deps = {}) {
     if (report.runtime_validation_path) emit(stdout, `runtime_validation_path: ${String(report.runtime_validation_path)}`);
     if (report.oauth_credentials_path) emit(stdout, `oauth_credentials_path: ${String(report.oauth_credentials_path)}`);
   });
-  program.command("register").option("--confirm", "confirm the draft registration immediately and publish it when the self-serve checks pass", false).option("--submit-review", "legacy alias: publish immediately if your environment still routes through submit-review", false).option("--json", "emit machine-readable JSON", false).argument("[path]", ".", "project path").action(async (path, options) => {
-    const report = await runRegistration(path, { confirm: options.confirm, submit_review: options.submitReview }, deps);
+  program.command("register").option("--confirm", "explicitly confirm the registration; this is the default unless --draft-only is set", false).option("--draft-only", "create or refresh the draft without confirming publication", false).option("--submit-review", "legacy alias: publish immediately if your environment still routes through submit-review", false).option("--json", "emit machine-readable JSON", false).argument("[path]", ".", "project path").action(async (path, options) => {
+    const draftOnly = Boolean(options.draftOnly);
+    if (draftOnly && options.confirm) {
+      throw new SiglumeProjectError("--draft-only cannot be combined with --confirm.");
+    }
+    if (draftOnly && options.submitReview) {
+      throw new SiglumeProjectError("--draft-only cannot be combined with --submit-review.");
+    }
+    const shouldConfirm = Boolean(options.confirm) || !draftOnly && !options.submitReview;
+    const report = await runRegistration(path, { confirm: shouldConfirm, draft_only: draftOnly, submit_review: options.submitReview }, deps);
     if (options.json) {
       emit(stdout, renderJson(report));
     } else {
       const receipt = report.receipt;
-      if (report.confirmation) {
-        emit(stdout, "Listing published.");
-      } else if (report.review) {
-        emit(stdout, "Listing published via legacy submit-review alias.");
+      const published = Boolean(report.confirmation || report.review);
+      if (published && receipt.registration_mode === "upgrade") {
+        emit(stdout, "Upgrade registered.");
+      } else if (published) {
+        emit(stdout, "Registration accepted.");
       } else if (receipt.registration_mode === "upgrade") {
         emit(stdout, "Upgrade staged.");
       } else if (receipt.registration_mode === "refresh") {
@@ -8842,10 +8742,12 @@ async function runCli(argv, deps = {}) {
       if (receipt.request_id) emit(stdout, `request_id: ${receipt.request_id}`);
       if (report.confirmation) {
         const confirmation = report.confirmation;
+        emit(stdout, "Listing published.");
         if (confirmation.status) emit(stdout, `confirmation_status: ${confirmation.status}`);
         if (confirmation.release?.release_status) emit(stdout, `release_status: ${confirmation.release.release_status}`);
       } else if (report.review) {
         const review = report.review;
+        emit(stdout, "Listing published via legacy submit-review alias.");
         if (review.status) emit(stdout, `publish_status: ${review.status}`);
       }
       const preflight = report.registration_preflight;