@siglume/api-sdk 0.7.5 → 0.8.0

package/dist/bin/siglume.js

@@ -1330,6 +1330,9 @@ function parseListing(data) {
     short_description: stringOrNull(data.short_description),
     docs_url: stringOrNull(data.docs_url),
     support_contact: stringOrNull(data.support_contact),
+    seller_display_name: stringOrNull(data.seller_display_name),
+    seller_homepage_url: stringOrNull(data.seller_homepage_url),
+    seller_social_url: stringOrNull(data.seller_social_url),
     review_status: stringOrNull(data.review_status),
     review_note: stringOrNull(data.review_note),
     submission_blockers: Array.isArray(data.submission_blockers) ? data.submission_blockers.filter((item) => typeof item === "string") : [],
@@ -2511,11 +2514,15 @@ var init_client = __esm({
       max_retries;
       fetchImpl;
       pendingConfirmations = /* @__PURE__ */ new Map();
-      constructor(options) {
-        if (!options.api_key) {
-          throw new SiglumeClientError("SIGLUME_API_KEY is required.");
+      constructor(options = {}) {
+        const envApiKey = typeof process !== "undefined" ? process.env?.SIGLUME_API_KEY : void 0;
+        const resolvedApiKey = (options.api_key ?? envApiKey ?? "").trim();
+        if (!resolvedApiKey) {
+          throw new SiglumeClientError(
+            "SIGLUME_API_KEY is required. Pass it as the api_key option or set the SIGLUME_API_KEY env var."
+          );
         }
-        this.api_key = options.api_key;
+        this.api_key = resolvedApiKey;
         this.agent_key = options.agent_key?.trim() || void 0;
         this.base_url = (options.base_url ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
         this.timeout_ms = Math.max(1, options.timeout_ms ?? 15e3);
@@ -2542,6 +2549,13 @@ var init_client = __esm({
         if (options.runtime_validation) {
           payload.runtime_validation = coerceMapping(options.runtime_validation, "runtime_validation");
         }
+        if (options.oauth_credentials) {
+          payload.oauth_credentials = Array.isArray(options.oauth_credentials) ? {
+            items: options.oauth_credentials.map(
+              (item, index) => coerceMapping(item, `oauth_credentials[${index}]`)
+            )
+          } : coerceMapping(options.oauth_credentials, "oauth_credentials");
+        }
         if (options.metadata) {
           payload.metadata = coerceMapping(options.metadata, "metadata");
         }
@@ -2560,6 +2574,8 @@ var init_client = __esm({
           "docs_url",
           "documentation_url",
           "support_contact",
+          "seller_homepage_url",
+          "seller_social_url",
           "jurisdiction",
           "price_model",
           "price_value_minor",
@@ -2575,10 +2591,14 @@ var init_client = __esm({
         }
         const docsUrl = String(manifestPayload.docs_url ?? manifestPayload.documentation_url ?? "").trim();
         const supportContact = String(manifestPayload.support_contact ?? "").trim();
-        if (docsUrl || supportContact) {
+        const sellerHomepageUrl = String(manifestPayload.seller_homepage_url ?? "").trim();
+        const sellerSocialUrl = String(manifestPayload.seller_social_url ?? "").trim();
+        if (docsUrl || supportContact || sellerHomepageUrl || sellerSocialUrl) {
           const publisherIdentity = {
             documentation_url: docsUrl || null,
-            support_contact: supportContact || null
+            support_contact: supportContact || null,
+            seller_homepage_url: sellerHomepageUrl || null,
+            seller_social_url: sellerSocialUrl || null
           };
           payload.publisher_identity = publisherIdentity;
           payload.legal = { publisher_identity: publisherIdentity };
@@ -2592,36 +2612,30 @@ var init_client = __esm({
         return {
           listing_id,
           status: String(data.status ?? "draft"),
+          registration_mode: stringOrNull(data.registration_mode),
+          listing_status: stringOrNull(data.listing_status),
           auto_manifest: toRecord(data.auto_manifest),
           confidence: toRecord(data.confidence),
           validation_report: toRecord(data.validation_report),
+          oauth_status: toRecord(data.oauth_status),
           review_url: stringOrNull(data.review_url),
           trace_id: meta.trace_id,
           request_id: meta.request_id
         };
       }
       async confirm_registration(listing_id, options = {}) {
-        const pending = this.pendingConfirmations.get(listing_id);
-        const manifestPayload = options.manifest ? coerceMapping(options.manifest, "manifest") : pending?.manifest ?? {};
-        const toolManualPayload = options.tool_manual ? coerceMapping(options.tool_manual, "tool_manual") : pending?.tool_manual ?? {};
-        const overrides = {};
-        for (const fieldName of ["name", "job_to_be_done"]) {
-          if (manifestPayload[fieldName]) {
-            overrides[fieldName] = manifestPayload[fieldName];
-          }
-        }
-        if (Object.keys(toolManualPayload).length > 0) {
-          overrides.tool_manual = toolManualPayload;
-        }
+        void options;
         const payload = { approved: true };
-        if (Object.keys(overrides).length > 0) {
-          payload.overrides = overrides;
-        }
         const [data, meta] = await this.request("POST", `/market/capabilities/${listing_id}/confirm-auto-register`, { json_body: payload });
         this.pendingConfirmations.delete(listing_id);
+        const checklist = isRecord(data.checklist) ? Object.fromEntries(
+          Object.entries(data.checklist).map(([key, value]) => [key, Boolean(value)])
+        ) : {};
         return {
           listing_id: String(data.listing_id ?? listing_id),
           status: String(data.status ?? ""),
+          message: stringOrNull(data.message),
+          checklist,
           release: toRecord(data.release),
           quality: parseRegistrationQuality(toRecord(data.quality)),
           trace_id: meta.trace_id,
@@ -4578,7 +4592,7 @@ ${details}` : summary;
         const headers = new Headers({
           Authorization: `Bearer ${this.api_key}`,
           Accept: "application/json",
-          "User-Agent": "siglume-api-sdk-ts/0.6.0"
+          "User-Agent": "siglume-api-sdk-ts/0.7.6"
         });
         if (options.headers) {
           for (const [key, value] of Object.entries(options.headers)) {
@@ -4780,7 +4794,7 @@ var init_metering = __esm({
       fetchImpl;
       constructor(options) {
         this.client = new SiglumeClient(options);
-        this.api_key = options.api_key;
+        this.api_key = this.client.api_key;
         this.base_url = (options.base_url ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
         this.timeout_ms = Math.max(1, options.timeout_ms ?? 15e3);
         this.max_retries = Math.max(1, Math.trunc(options.max_retries ?? 3));
@@ -4826,7 +4840,7 @@ var init_metering = __esm({
         const headers = new Headers({
           Authorization: `Bearer ${this.api_key}`,
           Accept: "application/json",
-          "User-Agent": "siglume-api-sdk-ts/0.6.0"
+          "User-Agent": "siglume-api-sdk-ts/0.7.6"
         });
         let body;
         if (options.json_body) {
@@ -7141,6 +7155,15 @@ async function loadProject(path = ".") {
   const tool_manual = tool_manual_path ? JSON.parse(await readFile(tool_manual_path, "utf8")) : buildToolManualTemplate(manifest);
   const runtime_validation_path = await findRuntimeValidationPath(root_dir);
   const runtime_validation = runtime_validation_path ? await loadJsonObject(runtime_validation_path, "runtime_validation") : void 0;
+  const oauth_credentials_path = await findOauthCredentialsPath(root_dir);
+  let oauth_credentials;
+  if (oauth_credentials_path) {
+    const parsed = JSON.parse(await readFile(oauth_credentials_path, "utf8"));
+    if (!isRecord(parsed) && !Array.isArray(parsed)) {
+      throw new SiglumeProjectError("oauth_credentials must be a JSON object or array");
+    }
+    oauth_credentials = parsed;
+  }
   return {
     root_dir,
     adapter_path,
@@ -7149,9 +7172,110 @@ async function loadProject(path = ".") {
     tool_manual_path: tool_manual_path ?? void 0,
     tool_manual,
     runtime_validation_path: runtime_validation_path ?? void 0,
-    runtime_validation
+    runtime_validation,
+    oauth_credentials_path: oauth_credentials_path ?? void 0,
+    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 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];
+    }
+  }
+  return null;
+}
+function requiredOauthProviders(requirements) {
+  const providers = [];
+  for (const item of requirements ?? []) {
+    const providerKey = oauthProviderKeyFromRequirement(item);
+    if (providerKey && !providers.includes(providerKey)) {
+      providers.push(providerKey);
+    }
+  }
+  return providers;
+}
+function oauthProviderRecordsMap(payload) {
+  if (!payload) {
+    return {};
+  }
+  const items = Array.isArray(payload) ? payload : Array.isArray(payload.items) ? payload.items : [payload];
+  const resolved = {};
+  for (const [index, item] of items.entries()) {
+    if (!isRecord(item)) {
+      throw new SiglumeProjectError(`oauth_credentials[${index}] must be a JSON object.`);
+    }
+    const providerKey = oauthProviderKeyFromRequirement(item.provider_key ?? item.provider);
+    if (!providerKey) {
+      throw new SiglumeProjectError(`oauth_credentials[${index}].provider_key is unsupported.`);
+    }
+    const clientId = String(item.client_id ?? "").trim();
+    const clientSecret = String(item.client_secret ?? "").trim();
+    if (!clientId || !clientSecret) {
+      throw new SiglumeProjectError(`oauth_credentials[${index}] must include client_id and client_secret.`);
+    }
+    const rawScopes = item.required_scopes ?? item.scopes;
+    let scopes = [];
+    if (rawScopes == null) {
+      scopes = [];
+    } else if (!Array.isArray(rawScopes)) {
+      throw new SiglumeProjectError(`oauth_credentials[${index}].required_scopes must be a JSON array.`);
+    } else {
+      scopes = rawScopes.map((scope) => String(scope ?? "").trim()).filter(Boolean);
+    }
+    resolved[providerKey] = {
+      provider_key: providerKey,
+      client_id: clientId,
+      client_secret: clientSecret,
+      required_scopes: scopes
+    };
+  }
+  return resolved;
+}
+function canonicalOauthCredentialsPayload(payload) {
+  const records = oauthProviderRecordsMap(payload);
+  const providerKeys = Object.keys(records).sort();
+  if (providerKeys.length === 0) {
+    return void 0;
+  }
+  return {
+    items: providerKeys.map((providerKey) => records[providerKey])
+  };
+}
+function ensureRequiredOauthCredentials(project) {
+  const requiredProviders = requiredOauthProviders(project.manifest.required_connected_accounts ?? []);
+  if (requiredProviders.length === 0) {
+    return;
+  }
+  const provided = new Set(Object.keys(oauthProviderRecordsMap(project.oauth_credentials)));
+  const missing = requiredProviders.filter((provider) => !provided.has(provider));
+  if (missing.length === 0) {
+    return;
+  }
+  const path = project.oauth_credentials_path ?? join(project.root_dir, "oauth_credentials.json");
+  throw new SiglumeProjectError(
+    `${path} is required for OAuth-backed APIs. Missing provider seeds: ${missing.join(", ")}`
+  );
+}
 async function validateProject(path = ".", deps = {}) {
   const project = await loadProject(path);
   const manifest_issues = await projectValidationIssues(project);
@@ -7188,17 +7312,31 @@ function ensureManifestPublisherIdentity(project) {
   const manifestPayload = project.manifest;
   const docsUrl = String(manifestPayload.docs_url ?? manifestPayload.documentation_url ?? "").trim();
   const supportContact = String(manifestPayload.support_contact ?? "").trim();
+  const sellerHomepageUrl = String(manifestPayload.seller_homepage_url ?? "").trim();
+  const sellerSocialUrl = String(manifestPayload.seller_social_url ?? "").trim();
   const jurisdiction = String(manifestPayload.jurisdiction ?? "").trim();
   const issues = [];
   if (!docsUrl) {
     issues.push("manifest.docs_url is required");
   } else if (looksLikePlaceholder(docsUrl)) {
     issues.push("manifest.docs_url must be replaced with your public documentation URL");
+  } else if (!looksLikeHttpUrl(docsUrl)) {
+    issues.push("manifest.docs_url must be an http(s) URL");
+  } else if (looksLikeRootUrl(docsUrl)) {
+    issues.push("manifest.docs_url must be a dedicated API usage page, not a root homepage URL");
   }
   if (!supportContact) {
     issues.push("manifest.support_contact is required");
   } else if (looksLikePlaceholder(supportContact)) {
     issues.push("manifest.support_contact must be replaced with your real support email or support URL");
+  } else if (!looksLikeEmail(supportContact) && !looksLikeHttpUrl(supportContact)) {
+    issues.push("manifest.support_contact must be a real email address or http(s) support URL");
+  }
+  if (sellerHomepageUrl && (looksLikePlaceholder(sellerHomepageUrl) || !looksLikeHttpUrl(sellerHomepageUrl))) {
+    issues.push("manifest.seller_homepage_url must be a real http(s) official homepage URL when provided");
+  }
+  if (sellerSocialUrl && (looksLikePlaceholder(sellerSocialUrl) || !looksLikeHttpUrl(sellerSocialUrl))) {
+    issues.push("manifest.seller_social_url must be a real http(s) official social/profile URL when provided");
   }
   if (!jurisdiction) issues.push("manifest.jurisdiction is required");
   if (issues.length > 0) {
@@ -7210,7 +7348,25 @@ ${issues.map((issue2) => `- ${issue2}`).join("\n")}`
 }
 function looksLikePlaceholder(value) {
   const normalized = value.trim().toLowerCase();
-  return !normalized || normalized.includes("example.com") || normalized.startsWith("replace-with-") || normalized.startsWith("your-") || normalized.includes("your-domain") || normalized.includes("localhost") || normalized.includes("127.0.0.1") || normalized.includes("0.0.0.0");
+  return !normalized || normalized.includes("example.com") || normalized.includes("example.net") || normalized.includes("example.org") || normalized.startsWith("replace-with-") || normalized.startsWith("your-") || normalized.includes("your-domain") || normalized.includes("localhost") || normalized.includes("127.0.0.1") || normalized.includes("0.0.0.0");
+}
+function looksLikeHttpUrl(value) {
+  try {
+    const parsed = new URL(value.trim());
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function looksLikeRootUrl(value) {
+  if (!looksLikeHttpUrl(value)) return false;
+  const parsed = new URL(value.trim());
+  return parsed.pathname.replace(/^\/+|\/+$/g, "") === "";
+}
+function looksLikeEmail(value) {
+  const normalized = value.trim();
+  const domain = normalized.split("@").at(-1) ?? "";
+  return normalized.includes("@") && !normalized.includes(" ") && domain.includes(".") && !normalized.startsWith("@");
 }
 function runtimePlaceholderIssues(runtimeValidation) {
   const issues = [];
@@ -7270,6 +7426,9 @@ async function registrationPreflight(project, client) {
   const manifestIssues = await projectValidationIssues(project);
   const [toolManualValid, toolManualIssues] = validate_tool_manual(project.tool_manual);
   const remoteQuality = await client.preview_quality_score(project.tool_manual);
+  const requiredOauthProvidersList = requiredOauthProviders(project.manifest.required_connected_accounts ?? []);
+  const oauthProviderRecords = oauthProviderRecordsMap(project.oauth_credentials);
+  const missingOauthProviders = requiredOauthProvidersList.filter((provider) => !oauthProviderRecords[provider]);
   const blockingToolManualIssues = toolManualIssues.filter((issue2) => issue2.severity === "error");
   const errors = [
     ...manifestIssues.map((issue2) => String(issue2)),
@@ -7281,11 +7440,17 @@ async function registrationPreflight(project, client) {
   if (!remoteQualityOk(remoteQuality)) {
     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(", ")}`);
+  }
   const preflight = {
     manifest_issues: manifestIssues,
     tool_manual_valid: toolManualValid,
     tool_manual_issues: toolManualIssues.map((issue2) => toJsonable(issue2)),
     remote_quality: toJsonable(remoteQuality),
+    required_oauth_providers: requiredOauthProvidersList,
+    oauth_credentials_path: project.oauth_credentials_path ?? null,
+    oauth_missing_providers: missingOauthProviders,
     ok: errors.length === 0
   };
   if (errors.length > 0) {
@@ -7301,6 +7466,7 @@ async function runRegistration(path = ".", options = {}, deps = {}) {
   ensureExplicitToolManual(project);
   ensureManifestPublisherIdentity(project);
   ensureRuntimeValidationReady(project);
+  ensureRequiredOauthCredentials(project);
   const client = await createClient(deps);
   const preflight = await registrationPreflight(project, client);
   let developerPortalPreflight = null;
@@ -7309,18 +7475,20 @@ async function runRegistration(path = ".", options = {}, deps = {}) {
     const verifiedDestination = portal.payout_readiness?.verified_destination;
     if (verifiedDestination !== true) {
       throw new SiglumeProjectError(
-        "Paid API registration requires a verified Polygon payout destination. Open https://siglume.com/owner/publish or call GET /v1/market/developer/portal until payout_readiness.verified_destination is true."
+        "Paid API registration requires a verified Polygon payout destination. Open https://siglume.com/owner/credits/payout and confirm the embedded-wallet payout token, or call GET /v1/market/developer/portal until payout_readiness.verified_destination is true."
       );
     }
     developerPortalPreflight = toJsonable(portal);
   }
   const receipt = await client.auto_register(project.manifest, project.tool_manual, {
-    runtime_validation: project.runtime_validation
+    runtime_validation: project.runtime_validation,
+    oauth_credentials: canonicalOauthCredentialsPayload(project.oauth_credentials)
   });
   const result = {
     receipt: toJsonable(receipt),
     registration_preflight: preflight,
-    runtime_validation_path: project.runtime_validation_path ?? null
+    runtime_validation_path: project.runtime_validation_path ?? null,
+    oauth_credentials_path: project.oauth_credentials_path ?? null
   };
   if (developerPortalPreflight) {
     result.developer_portal_preflight = developerPortalPreflight;
@@ -7335,6 +7503,37 @@ async function runRegistration(path = ".", options = {}, deps = {}) {
   }
   return result;
 }
+async function runPreflight(path = ".", deps = {}) {
+  const project = await loadProject(path);
+  ensureExplicitToolManual(project);
+  ensureManifestPublisherIdentity(project);
+  ensureRuntimeValidationReady(project);
+  ensureRequiredOauthCredentials(project);
+  const client = await createClient(deps);
+  const preflight = await registrationPreflight(project, client);
+  let developerPortalPreflight = null;
+  if (String(project.manifest.price_model ?? "free").toLowerCase() !== "free") {
+    const portal = await client.get_developer_portal();
+    const verifiedDestination = portal.payout_readiness?.verified_destination;
+    if (verifiedDestination !== true) {
+      throw new SiglumeProjectError(
+        "Paid API registration requires a verified Polygon payout destination. Open https://siglume.com/owner/credits/payout and confirm the embedded-wallet payout token, or call GET /v1/market/developer/portal until payout_readiness.verified_destination is true."
+      );
+    }
+    developerPortalPreflight = toJsonable(portal);
+  }
+  const result = {
+    ok: true,
+    adapter_path: project.adapter_path,
+    registration_preflight: preflight,
+    runtime_validation_path: project.runtime_validation_path ?? null,
+    oauth_credentials_path: project.oauth_credentials_path ?? null
+  };
+  if (developerPortalPreflight) {
+    result.developer_portal_preflight = developerPortalPreflight;
+  }
+  return result;
+}
 async function createSupportCaseReport(options, deps = {}) {
   const client = await createClient(deps);
   const supportCase = await client.create_support_case(options.subject, options.body, { trace_id: options.trace_id });
@@ -7381,8 +7580,12 @@ async function writeInitTemplate(template, destination) {
   const manifest_path = join(root, "manifest.json");
   const tool_manual_path = join(root, "tool_manual.json");
   const runtime_validation_path = join(root, "runtime_validation.json");
+  const gitignore_path = join(root, ".gitignore");
   const readme_path = join(root, "README.md");
-  for (const filePath of [adapter_path, manifest_path, tool_manual_path, runtime_validation_path, readme_path]) {
+  const docs_dir = join(root, "docs");
+  await mkdir(docs_dir, { recursive: true });
+  const docs_usage_path = join(docs_dir, "api-usage.md");
+  for (const filePath of [adapter_path, manifest_path, tool_manual_path, runtime_validation_path, docs_usage_path, readme_path]) {
     if (existsSync(filePath)) {
       throw new SiglumeProjectError(`${basename(filePath)} already exists in ${root}`);
     }
@@ -7393,8 +7596,10 @@ async function writeInitTemplate(template, destination) {
   await writeFile(manifest_path, renderJson(manifest), "utf8");
   await writeFile(tool_manual_path, renderJson(toolManual), "utf8");
   await writeFile(runtime_validation_path, renderJson(buildRuntimeValidationTemplate(toolManual)), "utf8");
+  await writeFile(docs_usage_path, apiUsageDocsTemplate(manifest), "utf8");
+  await writeOrMergeGitignore(gitignore_path);
   await writeFile(readme_path, readmeTemplate(template), "utf8");
-  return [adapter_path, manifest_path, tool_manual_path, runtime_validation_path, readme_path];
+  return [adapter_path, manifest_path, tool_manual_path, runtime_validation_path, docs_usage_path, gitignore_path, readme_path];
 }
 async function listOperationCatalog(options = {}, deps = {}) {
   const resolvedAgentId = String(options.agent_id ?? "").trim();
@@ -7788,25 +7993,132 @@ 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`: public endpoint and review-key checks used by auto-register",
+    "- `runtime_validation.json`: local public endpoint and review-key checks used by auto-register",
+    "- `docs/api-usage.md`: publishable API usage guide template for `docs_url`",
+    "- `.gitignore`: keeps runtime review keys and OAuth client secrets 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` and `support_contact` with your public documentation and support contact.",
-    "- In `runtime_validation.json`, replace the public URL and review-key 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.",
+    "- If the API uses seller-side OAuth, create a local `oauth_credentials.json` next to the adapter.",
+    "- Do not commit real review keys or OAuth client secrets; the generated `.gitignore` excludes those files.",
+    "- Because `runtime_validation.json` is ignored, GitHub samples do not commit review-key values.",
     "",
     "## Commands",
     "",
+    "Start locally without a Siglume API key:",
+    "",
     "```bash",
-    "siglume validate .",
     "siglume test .",
     "npm test -- tests/test_adapter.ts",
+    "siglume score . --offline",
+    "```",
+    "",
+    "After placeholders are replaced and `SIGLUME_API_KEY` is issued from Developer Portal -> CLI / API keys, run the server-aligned checks:",
+    "",
+    "```bash",
+    "siglume validate .",
     "siglume score . --remote",
+    "siglume preflight .",
+    "siglume register .",
+    "# inspect the draft, then explicitly approve publish:",
     "siglume register . --confirm",
     "```",
     ""
   ].join("\n");
 }
+function apiUsageDocsTemplate(manifest) {
+  const name = String(manifest.name ?? manifest.capability_key ?? "Siglume API");
+  const capabilityKey = String(manifest.capability_key ?? "replace-with-capability-key");
+  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 supportContact = String(manifest.support_contact ?? "replace-with-support-contact");
+  return [
+    `# ${name} API Usage Guide`,
+    "",
+    `This page is the dedicated public usage guide for the Siglume API listing \`${capabilityKey}\`.`,
+    "Publish this page at an anonymous HTTP 200 URL and use that URL as `docs_url`.",
+    "",
+    "Do not use your company homepage as `docs_url`; keep seller/company homepages in `seller_homepage_url`.",
+    "",
+    "## What This API Does",
+    "",
+    jobToBeDone,
+    "",
+    "## Permission Model",
+    "",
+    `- Permission class: \`${permissionClass}\``,
+    `- Price model: \`${priceModel}\``,
+    `- Required connected accounts: \`${requiredAccounts}\``,
+    "",
+    "## Inputs",
+    "",
+    "Describe the request fields your API accepts. Keep this aligned with `tool_manual.json` and `runtime_validation.json`.",
+    "",
+    "## Outputs",
+    "",
+    "Describe the response fields your API returns. Include the fields in `runtime_validation.expected_response_fields`.",
+    "",
+    "## Errors And Support",
+    "",
+    "Explain common error messages and how an owner should recover.",
+    "",
+    `Support contact: ${supportContact}`,
+    ""
+  ].join("\n");
+}
+function generatedGitignore() {
+  return [
+    "# Local secrets and registration-only runtime checks.",
+    ".env",
+    ".env.*",
+    "!.env.example",
+    "runtime_validation.json",
+    "runtime-validation.json",
+    "oauth_credentials.json",
+    "oauth-credentials.json",
+    "",
+    "# Python / test artifacts.",
+    "__pycache__/",
+    "*.py[cod]",
+    ".pytest_cache/",
+    ".mypy_cache/",
+    ".coverage",
+    "htmlcov/",
+    "dist/",
+    "build/",
+    "*.egg-info/",
+    "",
+    "# JavaScript tooling if this project also uses TypeScript helpers.",
+    "node_modules/",
+    "coverage/",
+    ""
+  ].join("\n");
+}
+async function writeOrMergeGitignore(filePath) {
+  const generated = generatedGitignore();
+  if (!existsSync(filePath)) {
+    await writeFile(filePath, generated, "utf8");
+    return;
+  }
+  const existing = await readFile(filePath, "utf8");
+  const existingEntries = new Set(existing.split(/\r?\n/).map((line) => line.trim()));
+  const additions = generated.split(/\r?\n/).filter((line) => line.trim() && !existingEntries.has(line.trim()));
+  if (additions.length === 0) {
+    return;
+  }
+  const prefix = existing.endsWith("\n") ? existing : `${existing}
+`;
+  await writeFile(filePath, `${prefix}
+# Siglume generated ignores.
+${additions.join("\n")}
+`, "utf8");
+}
 async function writeOperationTemplate(operation_key, destination, options = {}, deps = {}) {
   const root = resolve(destination);
   await mkdir(root, { recursive: true });
@@ -7817,9 +8129,22 @@ async function writeOperationTemplate(operation_key, destination, options = {},
   const manifest_path = join(root, "manifest.json");
   const tool_manual_path = join(root, "tool_manual.json");
   const runtime_validation_path = join(root, "runtime_validation.json");
+  const gitignore_path = join(root, ".gitignore");
   const readme_path = join(root, "README.md");
   const test_path = join(testsDir, "test_adapter.ts");
-  for (const filePath of [adapter_path, stubs_path, manifest_path, tool_manual_path, runtime_validation_path, readme_path, test_path]) {
+  const docs_dir = join(root, "docs");
+  await mkdir(docs_dir, { recursive: true });
+  const docs_usage_path = join(docs_dir, "api-usage.md");
+  for (const filePath of [
+    adapter_path,
+    stubs_path,
+    manifest_path,
+    tool_manual_path,
+    runtime_validation_path,
+    docs_usage_path,
+    readme_path,
+    test_path
+  ]) {
     if (existsSync(filePath)) {
       throw new SiglumeProjectError(`${basename(filePath)} already exists in ${root}`);
     }
@@ -7847,10 +8172,22 @@ async function writeOperationTemplate(operation_key, destination, options = {},
   await writeFile(manifest_path, renderJson(manifest), "utf8");
   await writeFile(tool_manual_path, renderJson(tool_manual), "utf8");
   await writeFile(runtime_validation_path, renderJson(buildRuntimeValidationTemplate(tool_manual)), "utf8");
+  await writeFile(docs_usage_path, apiUsageDocsTemplate(manifest), "utf8");
+  await writeOrMergeGitignore(gitignore_path);
   await writeFile(readme_path, operationReadmeTemplate(operation, manifest, warning), "utf8");
   await writeFile(test_path, operationTestSource(operation), "utf8");
   return {
-    files: [adapter_path, stubs_path, manifest_path, tool_manual_path, runtime_validation_path, readme_path, test_path],
+    files: [
+      adapter_path,
+      stubs_path,
+      manifest_path,
+      tool_manual_path,
+      runtime_validation_path,
+      docs_usage_path,
+      gitignore_path,
+      readme_path,
+      test_path
+    ],
     operation,
     report: {
       tool_manual_valid,
@@ -7999,6 +8336,15 @@ async function findRuntimeValidationPath(root_dir) {
   }
   return null;
 }
+async function findOauthCredentialsPath(root_dir) {
+  for (const name of ["oauth_credentials.json", "oauth-credentials.json"]) {
+    const candidate = join(root_dir, name);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
 async function loadJsonObject(path, label) {
   let payload;
   try {
@@ -8222,18 +8568,36 @@ function readmeTemplate(template) {
     "- `adapter.ts`: your AppAdapter implementation",
     "- `manifest.json`: serialized AppManifest snapshot",
     "- `tool_manual.json`: editable ToolManual draft for validation and registration",
-    "- `runtime_validation.json`: live API smoke-test contract used during 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 and OAuth client secrets out of Git",
     "",
     "Before registering, replace all generated placeholders:",
-    "- In `adapter.ts` and `manifest.json`, replace `docs_url` and `support_contact` with your public documentation and support contact.",
-    "- In `runtime_validation.json`, replace the public URL and review-key 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.",
+    "- If the API uses seller-side OAuth, create a local `oauth_credentials.json` next to the adapter.",
+    "- Do not commit real review keys or OAuth client secrets; the generated `.gitignore` excludes those files.",
+    "- Because `runtime_validation.json` is ignored, GitHub samples do not commit review-key values.",
     "",
     "Suggested workflow:",
     "",
+    "Start locally without a Siglume API key:",
+    "",
     "```bash",
-    "siglume validate .",
     "siglume test .",
+    "siglume score . --offline",
+    "```",
+    "",
+    "After placeholders are replaced and `SIGLUME_API_KEY` is issued from Developer Portal -> CLI / API keys, run the server-aligned checks:",
+    "",
+    "```bash",
+    "siglume validate .",
     "siglume score . --remote",
+    "siglume preflight .",
+    "siglume register .",
+    "# inspect the draft, then explicitly approve publish:",
     "siglume register . --confirm",
     "```",
     ""
@@ -8402,18 +8766,52 @@ async function runCli(argv, deps = {}) {
       throw new SiglumeProjectError("Score failed.");
     }
   });
-  program.command("register").option("--confirm", "confirm the draft registration immediately and submit it for review", false).option("--submit-review", "submit the draft for review if --confirm is not used", false).option("--json", "emit machine-readable JSON", false).argument("[path]", ".", "project path").action(async (path, options) => {
+  program.command("preflight").option("--json", "emit machine-readable JSON", false).argument("[path]", ".", "project path").action(async (path, options) => {
+    const report = await runPreflight(path, deps);
+    if (options.json) {
+      emit(stdout, renderJson(report));
+      return;
+    }
+    emit(stdout, "Preflight passed.");
+    const preflight = report.registration_preflight;
+    if (preflight?.remote_quality) {
+      emit(stdout, `preflight_quality: ${preflight.remote_quality.grade} (${preflight.remote_quality.overall_score}/100)`);
+    }
+    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);
     if (options.json) {
       emit(stdout, renderJson(report));
     } else {
       const receipt = report.receipt;
-      emit(stdout, "Draft listing created.");
+      if (report.confirmation) {
+        emit(stdout, "Listing published.");
+      } else if (report.review) {
+        emit(stdout, "Listing published via legacy submit-review alias.");
+      } else if (receipt.registration_mode === "upgrade") {
+        emit(stdout, "Upgrade staged.");
+      } else if (receipt.registration_mode === "refresh") {
+        emit(stdout, "Draft refreshed.");
+      } else {
+        emit(stdout, "Draft listing created.");
+      }
       emit(stdout, `listing_id: ${receipt.listing_id}`);
-      emit(stdout, `status: ${receipt.status}`);
+      emit(stdout, `receipt_status: ${receipt.status}`);
+      if (receipt.listing_status) emit(stdout, `listing_status: ${receipt.listing_status}`);
+      if (receipt.oauth_status) emit(stdout, `oauth_configured: ${Boolean(receipt.oauth_status.configured)}`);
       if (receipt.review_url) emit(stdout, `review_url: ${receipt.review_url}`);
       if (receipt.trace_id) emit(stdout, `trace_id: ${receipt.trace_id}`);
       if (receipt.request_id) emit(stdout, `request_id: ${receipt.request_id}`);
+      if (report.confirmation) {
+        const confirmation = report.confirmation;
+        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;
+        if (review.status) emit(stdout, `publish_status: ${review.status}`);
+      }
       const preflight = report.registration_preflight;
       if (preflight?.remote_quality) {
         emit(stdout, `preflight_quality: ${preflight.remote_quality.grade} (${preflight.remote_quality.overall_score}/100)`);