@siglume/api-sdk 1.2.2 → 2.0.0

package/README.md

@@ -27,7 +27,7 @@ Buyer-side discovery and export helpers are also included:
 import { SiglumeBuyerClient, to_anthropic_tool } from "@siglume/api-sdk";
 
 const buyer = new SiglumeBuyerClient({
-  api_key: process.env.SIGLUME_API_KEY ?? "sig_mock_key",
+  api_key: process.env.SIGLUME_OWNER_SESSION_BEARER!,
   default_agent_id: process.env.SIGLUME_AGENT_ID,
 });
 
@@ -73,7 +73,7 @@ siglume register . --company company_123
 
 `siglume register` reads `tool_manual.json`, the local Git-ignored
 `runtime_validation.json`. Generated projects keep runtime validation files
-Git-ignored because they can contain review keys. SDK / HTTP automation can pass
+Git-ignored because they hold the runtime auth header shared secret. 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 and confirms publication
@@ -88,6 +88,14 @@ public-order / morals compliance.
 For the canonical pricing reference, see
 [`../docs/pricing-and-billing.md`](../docs/pricing-and-billing.md).
 
+Developer-funded reward or incentive payouts are not normal SDK/API-key calls.
+Do not call MCP Gateway with `SIGLUME_API_KEY`, `cli_...`, `X-API-Key`, or
+`X-Siglume-API-Key`. Reward payout execution uses
+`https://mcp.siglume.com/` with `Authorization: Bearer mcpsk_...` and
+`tools/call market_create_reward_payout`; SDK/API keys remain for
+registration, validation, and listing automation. See
+[`../docs/web3-settlement.md#generic-reward-payouts`](../docs/web3-settlement.md#generic-reward-payouts).
+
 Use `price_model: PriceModel.USAGE_BASED` or `PriceModel.PER_ACTION` when the
 API must execute before the final operation is known. These listings are free to
 invoke up front. Your adapter returns the executed operation in
@@ -145,6 +153,15 @@ then calls the ACTION endpoint with the same token as `commit_token`. If payment
 fails, the ACTION call is never made. Use the default `"post"` timing only for
 read-only or reversible usage.
 
+Responsibility boundary: Siglume owns payment, authorization, platform
+idempotency, retry state, usage rows, and reconciliation state. Your API owns
+the provider-specific action and the proof that it committed. The platform does
+not infer whether an X post, email, CRM write, booking, or other external action
+happened. Return committed evidence only after the side effect committed;
+draft-only, preview, ambiguous, or `status="ready"` live-action results are not
+delivered results. See
+[`../docs/platform-api-boundary.md`](../docs/platform-api-boundary.md).
+
 After live or sandbox execution, inspect receipts with `siglume dev tail`,
 `siglume dev tail --listing-id <listing_id>`, or the SDK receipt helpers. The
 publisher listing view is privacy-redacted. See

package/dist/bin/siglume.cjs

@@ -354,7 +354,12 @@ var init_webhooks = __esm({
       "capability.published",
       "capability.delisted",
       "execution.completed",
-      "execution.failed"
+      "execution.failed",
+      "reward_payout.created",
+      "reward_payout.provider_pending",
+      "reward_paid",
+      "reward_payout.failed",
+      "reward_payout.cancelled"
     ];
     WEBHOOK_EVENT_SET = new Set(WEBHOOK_EVENT_TYPES);
   }
@@ -1404,6 +1409,23 @@ function validatePricingPlanFloor(plan, defaultCurrency) {
 function pricingPlanHasItems(plan) {
   return isRecord(plan) && Array.isArray(plan.items) && plan.items.length > 0;
 }
+function validateListingTextLengths(payload) {
+  const limits = {
+    short_description: LISTING_SHORT_DESCRIPTION_MAX_LENGTH,
+    job_to_be_done: LISTING_JOB_TO_BE_DONE_MAX_LENGTH,
+    description: LISTING_DESCRIPTION_MAX_LENGTH
+  };
+  for (const [fieldName, maxLength] of Object.entries(limits)) {
+    const value = payload[fieldName];
+    if (value === void 0 || value === null) continue;
+    if (typeof value !== "string") {
+      throw new SiglumeClientError(`AppManifest.${fieldName} must be a string when provided.`);
+    }
+    if (Array.from(value).length > maxLength) {
+      throw new SiglumeClientError(`AppManifest.${fieldName} must be at most ${maxLength} characters.`);
+    }
+  }
+}
 function buildToolManualQualityReport(payload) {
   const qualityBlock = isRecord(payload.quality) ? payload.quality : payload;
   const issues = [];
@@ -1961,139 +1983,6 @@ function parseInstalledToolReceiptStep(data) {
     raw: { ...data }
   };
 }
-function toRecordList(value) {
-  return Array.isArray(value) ? value.filter((item) => isRecord(item)).map((item) => ({ ...item })) : [];
-}
-function parsePartnerDashboard(data) {
-  return {
-    partner_id: String(data.partner_id ?? data.user_id ?? ""),
-    company_name: stringOrNull(data.company_name) ?? void 0,
-    plan: stringOrNull(data.plan) ?? void 0,
-    plan_label: stringOrNull(data.plan_label) ?? void 0,
-    month_bytes_used: Math.trunc(Number(data.month_bytes_used ?? 0)),
-    month_bytes_limit: Math.trunc(Number(data.month_bytes_limit ?? 0)),
-    month_usage_pct: Number(data.month_usage_pct ?? 0),
-    total_source_items: Math.trunc(Number(data.total_source_items ?? 0)),
-    has_billing: Boolean(data.has_billing ?? false),
-    has_subscription: Boolean(data.has_subscription ?? false),
-    raw: { ...data }
-  };
-}
-function parsePartnerUsage(data) {
-  return {
-    plan: stringOrNull(data.plan) ?? void 0,
-    month_bytes_used: Math.trunc(Number(data.month_bytes_used ?? 0)),
-    month_bytes_limit: Math.trunc(Number(data.month_bytes_limit ?? 0)),
-    month_bytes_remaining: Math.trunc(Number(data.month_bytes_remaining ?? 0)),
-    month_usage_pct: Number(data.month_usage_pct ?? 0),
-    raw: { ...data }
-  };
-}
-function parsePartnerApiKey(data) {
-  return {
-    credential_id: String(data.credential_id ?? data.id ?? ""),
-    name: stringOrNull(data.name) ?? void 0,
-    key_id: stringOrNull(data.key_id) ?? void 0,
-    allowed_source_types: Array.isArray(data.allowed_source_types) ? data.allowed_source_types.filter((item) => typeof item === "string") : [],
-    last_used_at: stringOrNull(data.last_used_at) ?? void 0,
-    created_at: stringOrNull(data.created_at) ?? void 0,
-    revoked: Boolean(data.revoked ?? false),
-    raw: { ...data }
-  };
-}
-function parsePartnerApiKeyHandle(data) {
-  const raw = Object.fromEntries(
-    Object.entries(data).filter(([key]) => key !== "ingest_key" && key !== "full_key")
-  );
-  return {
-    credential_id: String(raw.credential_id ?? raw.id ?? ""),
-    name: stringOrNull(raw.name) ?? void 0,
-    key_id: stringOrNull(raw.key_id) ?? void 0,
-    allowed_source_types: Array.isArray(raw.allowed_source_types) ? raw.allowed_source_types.filter((item) => typeof item === "string") : [],
-    masked_key_hint: stringOrNull(raw.masked_key_hint) ?? void 0,
-    raw
-  };
-}
-function parseAdsBilling(data) {
-  return {
-    currency: stringOrNull(data.currency) ?? void 0,
-    billing_mode: stringOrNull(data.billing_mode) ?? void 0,
-    month_spend_jpy: Math.trunc(Number(data.month_spend_jpy ?? 0)),
-    month_spend_usd: Math.trunc(Number(data.month_spend_usd ?? 0)),
-    all_time_spend_jpy: Math.trunc(Number(data.all_time_spend_jpy ?? 0)),
-    all_time_spend_usd: Math.trunc(Number(data.all_time_spend_usd ?? 0)),
-    total_impressions: Math.trunc(Number(data.total_impressions ?? 0)),
-    total_replies: Math.trunc(Number(data.total_replies ?? 0)),
-    has_billing: Boolean(data.has_billing ?? false),
-    has_subscription: Boolean(data.has_subscription ?? false),
-    invoices: toRecordList(data.invoices),
-    wallet: isRecord(data.wallet) ? { ...data.wallet } : null,
-    balances: toRecordList(data.balances),
-    supported_tokens: toRecordList(data.supported_tokens),
-    funding_instructions: isRecord(data.funding_instructions) ? { ...data.funding_instructions } : null,
-    mandate: isRecord(data.mandate) ? parsePlanWeb3Mandate(data.mandate) : null,
-    raw: { ...data }
-  };
-}
-function parseAdsBillingSettlement(data) {
-  return {
-    status: stringOrNull(data.status) ?? void 0,
-    message: stringOrNull(data.message ?? data.detail) ?? void 0,
-    settles_automatically: typeof data.settles_automatically === "boolean" ? data.settles_automatically : typeof data.auto_settles === "boolean" ? data.auto_settles : void 0,
-    cycle_key: stringOrNull(data.cycle_key) ?? void 0,
-    settled_at: stringOrNull(data.settled_at) ?? void 0,
-    raw: { ...data }
-  };
-}
-function parseAdsProfile(data) {
-  return {
-    has_profile: Boolean(data.has_profile ?? false),
-    company_name: stringOrNull(data.company_name) ?? void 0,
-    ad_currency: stringOrNull(data.ad_currency) ?? void 0,
-    has_billing: Boolean(data.has_billing ?? false),
-    raw: { ...data }
-  };
-}
-function parseAdsCampaign(data) {
-  return {
-    campaign_id: String(data.campaign_id ?? data.id ?? ""),
-    name: stringOrNull(data.name) ?? void 0,
-    target_url: stringOrNull(data.target_url) ?? void 0,
-    content_brief: stringOrNull(data.content_brief) ?? void 0,
-    target_topics: Array.isArray(data.target_topics) ? data.target_topics.filter((item) => typeof item === "string") : [],
-    posting_interval_minutes: Math.trunc(Number(data.posting_interval_minutes ?? 360)),
-    max_posts_per_day: Math.trunc(Number(data.max_posts_per_day ?? 4)),
-    currency: stringOrNull(data.currency) ?? void 0,
-    monthly_budget_jpy: Math.trunc(Number(data.monthly_budget_jpy ?? 0)),
-    cpm_jpy: Math.trunc(Number(data.cpm_jpy ?? 0)),
-    cpr_jpy: Math.trunc(Number(data.cpr_jpy ?? 0)),
-    monthly_budget_usd: Math.trunc(Number(data.monthly_budget_usd ?? 0)),
-    cpm_usd: Math.trunc(Number(data.cpm_usd ?? 0)),
-    cpr_usd: Math.trunc(Number(data.cpr_usd ?? 0)),
-    status: String(data.status ?? "active").trim().toLowerCase() || "active",
-    month_spend_jpy: Math.trunc(Number(data.month_spend_jpy ?? 0)),
-    month_spend_usd: Math.trunc(Number(data.month_spend_usd ?? 0)),
-    total_posts: Math.trunc(Number(data.total_posts ?? 0)),
-    total_impressions: Math.trunc(Number(data.total_impressions ?? 0)),
-    total_replies: Math.trunc(Number(data.total_replies ?? 0)),
-    next_post_at: stringOrNull(data.next_post_at) ?? void 0,
-    created_at: stringOrNull(data.created_at) ?? void 0,
-    raw: { ...data }
-  };
-}
-function parseAdsCampaignPost(data) {
-  return {
-    post_id: String(data.post_id ?? data.id ?? ""),
-    content_id: stringOrNull(data.content_id) ?? void 0,
-    cost_jpy: Math.trunc(Number(data.cost_jpy ?? 0)),
-    cost_usd: Math.trunc(Number(data.cost_usd ?? 0)),
-    impressions: Math.trunc(Number(data.impressions ?? 0)),
-    replies: Math.trunc(Number(data.replies ?? 0)),
-    status: stringOrNull(data.status) ?? void 0,
-    created_at: stringOrNull(data.created_at) ?? void 0,
-    raw: { ...data }
-  };
-}
 function parseWorksCategory(data) {
   return {
     key: String(data.key ?? ""),
@@ -2592,7 +2481,7 @@ function cloneJsonLike(value) {
   }
   return value;
 }
-var DEFAULT_SIGLUME_API_BASE, RETRYABLE_STATUS_CODES, MINIMUM_JPY_OPERATION_PRICE_CURRENCIES, CursorPageResult, SiglumeClient;
+var DEFAULT_SIGLUME_API_BASE, RETRYABLE_STATUS_CODES, MINIMUM_JPY_OPERATION_PRICE_CURRENCIES, LISTING_SHORT_DESCRIPTION_MAX_LENGTH, LISTING_JOB_TO_BE_DONE_MAX_LENGTH, LISTING_DESCRIPTION_MAX_LENGTH, CursorPageResult, SiglumeClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
@@ -2605,6 +2494,9 @@ var init_client = __esm({
     DEFAULT_SIGLUME_API_BASE = "https://siglume.com/v1";
     RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
     MINIMUM_JPY_OPERATION_PRICE_CURRENCIES = /* @__PURE__ */ new Set(["JPY", "JPYC"]);
+    LISTING_SHORT_DESCRIPTION_MAX_LENGTH = 60;
+    LISTING_JOB_TO_BE_DONE_MAX_LENGTH = 240;
+    LISTING_DESCRIPTION_MAX_LENGTH = 1e3;
     CursorPageResult = class {
       items;
       next_cursor;
@@ -2758,6 +2650,7 @@ var init_client = __esm({
         if (payload.pricing_plan !== void 0) {
           validatePricingPlanFloor(payload.pricing_plan, currency);
         }
+        validateListingTextLengths(payload);
         const priceModel = String(payload.price_model ?? "free").trim().toLowerCase();
         if ((priceModel === "usage_based" || priceModel === "per_action") && !pricingPlanHasItems(payload.pricing_plan)) {
           throw new SiglumeClientError("AppManifest.pricing_plan.items is required for usage_based/per_action pricing.");
@@ -3900,115 +3793,6 @@ var init_client = __esm({
         );
         return Array.isArray(data.result) ? data.result.filter((item) => isRecord(item)).map((item) => parseInstalledToolReceiptStep(item)) : [];
       }
-      async get_partner_dashboard(options = {}) {
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "partner.dashboard.get",
-          {},
-          { lang: options.lang }
-        );
-        return parsePartnerDashboard(execution.result);
-      }
-      async get_partner_usage(options = {}) {
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "partner.usage.get",
-          {},
-          { lang: options.lang }
-        );
-        return parsePartnerUsage(execution.result);
-      }
-      async list_partner_api_keys(options = {}) {
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "partner.keys.list",
-          {},
-          { lang: options.lang }
-        );
-        return Array.isArray(execution.result.keys) ? execution.result.keys.filter((item) => isRecord(item)).map((item) => parsePartnerApiKey(item)) : [];
-      }
-      async create_partner_api_key(options = {}) {
-        const payload = {};
-        if (options.name !== void 0) {
-          const normalizedName = String(options.name).trim();
-          if (!normalizedName) {
-            throw new SiglumeClientError("name cannot be empty.");
-          }
-          payload.name = normalizedName;
-        }
-        if (options.allowed_source_types !== void 0) {
-          if (!Array.isArray(options.allowed_source_types)) {
-            throw new SiglumeClientError("allowed_source_types must be a list of strings.");
-          }
-          payload.allowed_source_types = options.allowed_source_types.flatMap((item) => {
-            if (typeof item !== "string") {
-              throw new SiglumeClientError("allowed_source_types must contain only strings.");
-            }
-            const normalizedItem = item.trim();
-            return normalizedItem ? [normalizedItem] : [];
-          });
-        }
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "partner.keys.create",
-          payload,
-          { lang: options.lang }
-        );
-        return parsePartnerApiKeyHandle(execution.result);
-      }
-      async get_ads_billing(options = {}) {
-        const payload = {};
-        if (options.rail !== void 0 && String(options.rail).trim()) {
-          payload.rail = String(options.rail).trim().toLowerCase();
-        }
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "ads.billing.get",
-          payload,
-          { lang: options.lang }
-        );
-        return parseAdsBilling(execution.result);
-      }
-      async settle_ads_billing(options = {}) {
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "ads.billing.settle",
-          {},
-          { lang: options.lang }
-        );
-        return parseAdsBillingSettlement(execution.result);
-      }
-      async get_ads_profile(options = {}) {
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "ads.profile.get",
-          {},
-          { lang: options.lang }
-        );
-        return parseAdsProfile(execution.result);
-      }
-      async list_ads_campaigns(options = {}) {
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "ads.campaigns.list",
-          {},
-          { lang: options.lang }
-        );
-        return Array.isArray(execution.result.campaigns) ? execution.result.campaigns.filter((item) => isRecord(item)).map((item) => parseAdsCampaign(item)) : [];
-      }
-      async list_ads_campaign_posts(campaign_id, options = {}) {
-        const normalizedCampaignId = String(campaign_id ?? "").trim();
-        if (!normalizedCampaignId) {
-          throw new SiglumeClientError("campaign_id is required.");
-        }
-        const execution = await this.execute_owner_operation(
-          await this.resolveOwnerOperationAgentId(options.agent_id),
-          "ads.campaign_posts.list",
-          { campaign_id: normalizedCampaignId },
-          { lang: options.lang }
-        );
-        return Array.isArray(execution.result.posts) ? execution.result.posts.filter((item) => isRecord(item)).map((item) => parseAdsCampaignPost(item)) : [];
-      }
       // `market.proposals.*` currently rides on the public owner-operation execute
       // route. Read helpers return typed proposal records; guarded mutations return
       // the approval envelope without treating it as an error.
@@ -5938,12 +5722,15 @@ function validate_tool_manual(manualInput) {
     pushError("INVALID_TOOL_NAME", "tool_name must be alphanumeric + underscore, 3-64 chars", "tool_name");
   }
   for (const [fieldName, minLength, maxLength] of [
-    ["job_to_be_done", 10, 500],
+    ["job_to_be_done", 10, 240],
     ["summary_for_model", 10, 300]
   ]) {
     const value = manual[fieldName];
-    if (typeof value === "string" && (value.length < minLength || value.length > maxLength)) {
-      pushError("INVALID_TYPE", `${fieldName} must be ${minLength}-${maxLength} characters`, fieldName);
+    if (typeof value === "string") {
+      const length = Array.from(value).length;
+      if (length < minLength || length > maxLength) {
+        pushError("INVALID_TYPE", `${fieldName} must be ${minLength}-${maxLength} characters`, fieldName);
+      }
     }
   }
   const triggerConditions = manual.trigger_conditions;
@@ -7131,8 +6918,12 @@ function buildRuntimeValidationTemplate(toolManual) {
     healthcheck_url: "https://api.example.com/health",
     invoke_url: "https://api.example.com/invoke",
     invoke_method: "POST",
-    test_auth_header_name: "X-Siglume-Review-Key",
-    test_auth_header_value: "replace-with-dedicated-review-key",
+    // Shared secret Siglume attaches when it calls invoke_url at both
+    // registration validation and production runtime. Use a strong random
+    // value, keep it in the Git-ignored runtime_validation.json, and rotate it
+    // if it leaks. (legacy aliases: test_auth_header_name/value)
+    runtime_auth_header_name: "X-Siglume-Auth",
+    runtime_auth_header_value: "replace-with-strong-random-runtime-auth-secret",
     request_payload: requestPayload,
     expected_response_fields: expectedFields.length > 0 ? expectedFields : ["summary"],
     timeout_seconds: 10
@@ -7437,8 +7228,6 @@ function runtimePlaceholderIssues(runtimeValidation) {
     "public_base_url",
     "healthcheck_url",
     "invoke_url",
-    "test_auth_header_name",
-    "test_auth_header_value",
     "expected_response_fields"
   ]) {
     if (!runtimeValidation[fieldName]) {
@@ -7451,9 +7240,19 @@ function runtimePlaceholderIssues(runtimeValidation) {
       issues.push(`runtime_validation.${fieldName} must be replaced with your public production URL`);
     }
   }
-  const authValue = String(runtimeValidation.test_auth_header_value ?? "").trim();
+  const authName = String(
+    runtimeValidation.runtime_auth_header_name || runtimeValidation.test_auth_header_name || ""
+  ).trim();
+  if (!authName) {
+    issues.push("runtime_validation.runtime_auth_header_name is required");
+  }
+  const authValue = String(
+    runtimeValidation.runtime_auth_header_value || runtimeValidation.test_auth_header_value || ""
+  ).trim();
   if (!authValue || authValue.startsWith("replace-with-")) {
-    issues.push("runtime_validation.test_auth_header_value must be a dedicated review secret, not a placeholder");
+    issues.push(
+      "runtime_validation.runtime_auth_header_value must be a strong, dedicated runtime auth secret, not a placeholder"
+    );
   }
   const requestPayload = runtimeValidation.request_payload ?? runtimeValidation.test_request_body ?? runtimeValidation.runtime_sample ?? runtimeValidation.sample_request_payload ?? runtimeValidation.runtime_sample_request;
   if (!isRecord(requestPayload)) {
@@ -7468,7 +7267,7 @@ function runtimePlaceholderIssues(runtimeValidation) {
 function ensureRuntimeValidationReady(project) {
   if (!project.runtime_validation) {
     throw new SiglumeProjectError(
-      "runtime_validation.json is required for `siglume register`. Create it with public_base_url, healthcheck_url, invoke_url, dedicated review auth header, request_payload, and expected_response_fields."
+      "runtime_validation.json is required for `siglume register`. Create it with public_base_url, healthcheck_url, invoke_url, runtime auth header (runtime_auth_header_name/value), request_payload, and expected_response_fields."
     );
   }
   const issues = runtimePlaceholderIssues(project.runtime_validation);
@@ -8157,19 +7956,19 @@ function operationReadmeTemplate(operation, manifest, warning) {
     "- `stubs.ts`: mock fallback used when `SIGLUME_API_KEY` is not set",
     "- `manifest.json`: reviewable manifest snapshot",
     "- `tool_manual.json`: machine-generated ToolManual scaffold",
-    "- `runtime_validation.json`: local public endpoint and review-key checks used by auto-register",
+    "- `runtime_validation.json`: local public endpoint + runtime auth header checks used by auto-register",
     "- `docs/api-usage.md`: publishable API usage guide template for `docs_url`",
-    "- `.gitignore`: keeps runtime review keys out of Git",
+    "- `.gitignore`: keeps the runtime auth secret out of Git",
     "- `tests/test_adapter.ts`: smoke test for `AppTestHarness`",
     "",
     "Before registering, replace all generated placeholders:",
     "- In `adapter.ts` and `manifest.json`, replace `docs_url` with a dedicated public API usage guide, not a homepage.",
     "- Replace `support_contact` with a real support email address or public support URL.",
     "- Optional `seller_homepage_url` is the seller's official site and can stay blank.",
-    "- In the local `runtime_validation.json`, replace the public URL and review-key placeholders.",
+    "- In the local `runtime_validation.json`, replace the public URL and runtime auth header placeholders (runtime_auth_header_name/value).",
     "- If the API uses external OAuth, implement that flow in your API runtime and keep user tokens outside Siglume.",
-    "- Do not commit real review keys or external-provider secrets; the generated `.gitignore` excludes local secret files.",
-    "- Because `runtime_validation.json` is ignored, GitHub samples do not commit review-key values.",
+    "- Do not commit the real runtime auth secret or external-provider secrets; the generated `.gitignore` excludes local secret files.",
+    "- Because `runtime_validation.json` is ignored, GitHub samples do not commit runtime auth secret values.",
     "",
     "## Commands",
     "",
@@ -8238,7 +8037,7 @@ function apiUsageDocsTemplate(manifest) {
 }
 function generatedGitignore() {
   return [
-    "# Local secrets and registration-only runtime checks.",
+    "# Local secrets (incl. the runtime auth shared secret) and runtime checks.",
     ".env",
     ".env.*",
     "!.env.example",
@@ -8722,16 +8521,16 @@ function readmeTemplate(template) {
     "- `tool_manual.json`: editable ToolManual draft for validation and registration",
     "- `runtime_validation.json`: local live API smoke-test contract used during registration",
     "- `docs/api-usage.md`: publish this page and use its public URL as `docs_url`",
-    "- `.gitignore`: keeps runtime review keys out of Git",
+    "- `.gitignore`: keeps the runtime auth secret out of Git",
     "",
     "Before registering, replace all generated placeholders:",
     "- In `adapter.ts` and `manifest.json`, replace `docs_url` with a dedicated public API usage guide, not a homepage.",
     "- Replace `support_contact` with a real support email address or public support URL.",
     "- Optional `seller_homepage_url` is the seller's official site and can stay blank.",
-    "- In the local `runtime_validation.json`, replace the public URL and review-key placeholders.",
+    "- In the local `runtime_validation.json`, replace the public URL and runtime auth header placeholders (runtime_auth_header_name/value).",
     "- If the API uses external OAuth, implement that flow in your API runtime and keep user tokens outside Siglume.",
-    "- Do not commit real review keys or external-provider secrets; the generated `.gitignore` excludes local secret files.",
-    "- Because `runtime_validation.json` is ignored, GitHub samples do not commit review-key values.",
+    "- Do not commit the real runtime auth secret or external-provider secrets; the generated `.gitignore` excludes local secret files.",
+    "- Because `runtime_validation.json` is ignored, GitHub samples do not commit runtime auth secret values.",
     "",
     "Suggested workflow:",
     "",