diff --git a/src/authsome/auth/bundled_providers/ahrefs.json b/src/authsome/auth/bundled_providers/ahrefs.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/ahrefs.json
rename to src/authsome/auth/bundled_providers/ahrefs.jsonc
index 7e9ae07e..f246712f 100644
--- a/src/authsome/auth/bundled_providers/ahrefs.json
+++ b/src/authsome/auth/bundled_providers/ahrefs.jsonc
@@ -1,3 +1,7 @@
+// Ahrefs
+// SEO intelligence, backlink analysis, and keyword research APIs.
+// auth: api_key | flow: api_key
+// API keys are workspace-level; generate at ahrefs.com/user/api.
 {
   "schema_version": 1,
   "name": "ahrefs",
@@ -16,3 +20,4 @@
     "AHREFS_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/anthropic.jsonc b/src/authsome/auth/bundled_providers/anthropic.jsonc
new file mode 100644
index 00000000..b35e2e6e
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/anthropic.jsonc
@@ -0,0 +1,26 @@
+// Anthropic
+// API key access to Claude models via the Anthropic Messages API.
+// auth: api_key | flow: api_key
+// Anthropic uses x-api-key header — NOT Authorization Bearer like most providers.
+// Keys begin with "sk-ant-" and are generated at console.anthropic.com/keys.
+{
+  "schema_version": 1,
+  "name": "anthropic",
+  "display_name": "Anthropic",
+  "logo": "img.logo.dev/name/anthropic",
+  "description": "Anthropic API key for Claude model inference and the Messages API.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.anthropic.com",
+  "api_key": {
+    "header_name": "x-api-key",
+    "header_prefix": null,
+    "env_var": "ANTHROPIC_API_KEY",
+    "key_pattern": "^sk-ant-[A-Za-z0-9_-]+$",
+    "key_pattern_hint": "Anthropic API keys start with 'sk-ant-'. Generate one at console.anthropic.com/keys."
+  },
+  "export": {
+    "ANTHROPIC_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/apollo.json b/src/authsome/auth/bundled_providers/apollo.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/apollo.json
rename to src/authsome/auth/bundled_providers/apollo.jsonc
index 50671ac7..dff61d9a 100644
--- a/src/authsome/auth/bundled_providers/apollo.json
+++ b/src/authsome/auth/bundled_providers/apollo.jsonc
@@ -1,3 +1,7 @@
+// Apollo
+// Sales intelligence and prospecting data for go-to-market workflows.
+// auth: api_key | flow: api_key
+// API keys are found at app.apollo.io/#/settings/integrations/api.
 {
   "schema_version": 1,
   "name": "apollo",
@@ -16,3 +20,4 @@
     "APOLLO_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/ashby.json b/src/authsome/auth/bundled_providers/ashby.jsonc
similarity index 69%
rename from src/authsome/auth/bundled_providers/ashby.json
rename to src/authsome/auth/bundled_providers/ashby.jsonc
index 0d8bddbc..54d360f1 100644
--- a/src/authsome/auth/bundled_providers/ashby.json
+++ b/src/authsome/auth/bundled_providers/ashby.jsonc
@@ -1,3 +1,7 @@
+// Ashby
+// Recruiting operations, candidate data, and hiring workflow automation.
+// auth: api_key | flow: api_key
+// API keys are org-level; generate at app.ashbyhq.com/settings/api-keys.
 {
   "schema_version": 1,
   "name": "ashby",
@@ -16,3 +20,4 @@
     "ASHBY_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/atlassian.json b/src/authsome/auth/bundled_providers/atlassian.jsonc
similarity index 80%
rename from src/authsome/auth/bundled_providers/atlassian.json
rename to src/authsome/auth/bundled_providers/atlassian.jsonc
index d7db6bd8..6d0baeea 100644
--- a/src/authsome/auth/bundled_providers/atlassian.json
+++ b/src/authsome/auth/bundled_providers/atlassian.jsonc
@@ -1,3 +1,7 @@
+// Atlassian
+// Jira and Atlassian workspace APIs for project and issue management.
+// auth: oauth2 | flow: pkce
+// OAuth scopes cover both Jira and Confluence — add granular scopes as needed.
 {
   "schema_version": 1,
   "name": "atlassian",
@@ -28,3 +32,4 @@
     "ATLASSIAN_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/bedrock.jsonc b/src/authsome/auth/bundled_providers/bedrock.jsonc
new file mode 100644
index 00000000..24bb9b95
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/bedrock.jsonc
@@ -0,0 +1,26 @@
+// AWS Bedrock
+// AWS IAM access key for invoking foundation models via Amazon Bedrock.
+// auth: api_key | flow: api_key
+// The "API key" stored here is the AWS_ACCESS_KEY_ID. You must also set
+// AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION in your environment.
+// Bedrock uses AWS Signature V4 — the sdk/boto3 picks up credentials from env automatically.
+{
+  "schema_version": 1,
+  "name": "bedrock",
+  "display_name": "AWS Bedrock",
+  "logo": "img.logo.dev/name/amazon-web-services",
+  "description": "AWS IAM credentials for Amazon Bedrock foundation model inference.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://bedrock-runtime.us-east-1.amazonaws.com",
+  "api_key": {
+    "header_name": "X-Amz-Security-Token",
+    "header_prefix": null,
+    "env_var": "AWS_ACCESS_KEY_ID",
+    "key_pattern_hint": "Enter your AWS Access Key ID (AKIA... or ASIA...). Also set AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION."
+  },
+  "export": {
+    "AWS_ACCESS_KEY_ID": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/beehiiv.json b/src/authsome/auth/bundled_providers/beehiiv.jsonc
similarity index 68%
rename from src/authsome/auth/bundled_providers/beehiiv.json
rename to src/authsome/auth/bundled_providers/beehiiv.jsonc
index e81cf5c0..546b2eb5 100644
--- a/src/authsome/auth/bundled_providers/beehiiv.json
+++ b/src/authsome/auth/bundled_providers/beehiiv.jsonc
@@ -1,3 +1,7 @@
+// Beehiiv
+// Newsletter publishing, subscribers, and audience growth automation.
+// auth: api_key | flow: api_key
+// API keys are publication-level; generate at app.beehiiv.com/settings/integrations.
 {
   "schema_version": 1,
   "name": "beehiiv",
@@ -16,3 +20,4 @@
     "BEEHIIV_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/brave-search-mcp.jsonc b/src/authsome/auth/bundled_providers/brave-search-mcp.jsonc
new file mode 100644
index 00000000..e7d89fac
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/brave-search-mcp.jsonc
@@ -0,0 +1,25 @@
+// Brave Search MCP
+// API key for the Brave Search remote MCP server.
+// auth: api_key | flow: api_key
+// The key is injected as a Bearer token when connecting the MCP client to the server URL.
+// Keys are generated at brave.com/search/api/.
+{
+  "schema_version": 1,
+  "name": "brave-search-mcp",
+  "display_name": "Brave Search MCP",
+  "logo": "img.logo.dev/name/brave",
+  "description": "Brave Search API key for the remote MCP server — enables agents to search the web via MCP.",
+  "type": "mcp",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.search.brave.com/mcp",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "BRAVE_API_KEY",
+    "key_pattern_hint": "Brave Search API keys are generated at brave.com/search/api/."
+  },
+  "export": {
+    "BRAVE_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/brevo.json b/src/authsome/auth/bundled_providers/brevo.jsonc
similarity index 68%
rename from src/authsome/auth/bundled_providers/brevo.json
rename to src/authsome/auth/bundled_providers/brevo.jsonc
index c4251eeb..1bbdf5a7 100644
--- a/src/authsome/auth/bundled_providers/brevo.json
+++ b/src/authsome/auth/bundled_providers/brevo.jsonc
@@ -1,3 +1,7 @@
+// Brevo
+// Email marketing, transactional messaging, and contact management APIs.
+// auth: api_key | flow: api_key
+// Brevo was formerly Sendinblue. Keys at app.brevo.com/settings/keys/api.
 {
   "schema_version": 1,
   "name": "brevo",
@@ -16,3 +20,4 @@
     "BREVO_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/buffer.json b/src/authsome/auth/bundled_providers/buffer.jsonc
similarity index 68%
rename from src/authsome/auth/bundled_providers/buffer.json
rename to src/authsome/auth/bundled_providers/buffer.jsonc
index 5553e979..c7b50110 100644
--- a/src/authsome/auth/bundled_providers/buffer.json
+++ b/src/authsome/auth/bundled_providers/buffer.jsonc
@@ -1,3 +1,7 @@
+// Buffer
+// Social scheduling and publishing workflows for connected channels.
+// auth: api_key | flow: api_key
+// Scopes cover multiple social channels; remove scopes for channels you don't need.
 {
   "schema_version": 1,
   "name": "buffer",
@@ -16,3 +20,4 @@
     "BUFFER_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/calendly.json b/src/authsome/auth/bundled_providers/calendly.jsonc
similarity index 69%
rename from src/authsome/auth/bundled_providers/calendly.json
rename to src/authsome/auth/bundled_providers/calendly.jsonc
index 0dcc4789..93632b34 100644
--- a/src/authsome/auth/bundled_providers/calendly.json
+++ b/src/authsome/auth/bundled_providers/calendly.jsonc
@@ -1,3 +1,7 @@
+// Calendly
+// Scheduling links, events, invitees, and calendar booking automation.
+// auth: api_key | flow: api_key
+// OAuth token provides access to the user's event types and scheduled events.
 {
   "schema_version": 1,
   "name": "calendly",
@@ -16,3 +20,4 @@
     "CALENDLY_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/clearbit.json b/src/authsome/auth/bundled_providers/clearbit.jsonc
similarity index 67%
rename from src/authsome/auth/bundled_providers/clearbit.json
rename to src/authsome/auth/bundled_providers/clearbit.jsonc
index 450b4768..778c420b 100644
--- a/src/authsome/auth/bundled_providers/clearbit.json
+++ b/src/authsome/auth/bundled_providers/clearbit.jsonc
@@ -1,3 +1,7 @@
+// Clearbit
+// Company and contact enrichment data for sales and marketing workflows.
+// auth: api_key | flow: api_key
+// API keys are account-level; some endpoints require different keys (Enrichment vs. Reveal).
 {
   "schema_version": 1,
   "name": "clearbit",
@@ -16,3 +20,4 @@
     "CLEARBIT_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/cloudflare-mcp.jsonc b/src/authsome/auth/bundled_providers/cloudflare-mcp.jsonc
new file mode 100644
index 00000000..5f10d59f
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/cloudflare-mcp.jsonc
@@ -0,0 +1,27 @@
+// Cloudflare MCP
+// Cloudflare API token for the remote Cloudflare MCP server.
+// auth: api_key | flow: api_key
+// Distinct from the cloudflare.jsonc app provider which covers the REST API.
+// This provider targets the Cloudflare remote MCP server endpoint.
+// Create a scoped API token at dash.cloudflare.com/profile/api-tokens.
+{
+  "schema_version": 1,
+  "name": "cloudflare-mcp",
+  "display_name": "Cloudflare MCP",
+  "logo": "img.logo.dev/name/cloudflare",
+  "description": "Cloudflare API token for the remote MCP server — enables agents to manage zones, Workers, and DNS records via MCP.",
+  "type": "mcp",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://mcp.cloudflare.com",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "CLOUDFLARE_API_TOKEN",
+    "key_pattern": "^[A-Za-z0-9_-]{40}$",
+    "key_pattern_hint": "Cloudflare API tokens are 40-character strings. Create a scoped token at dash.cloudflare.com/profile/api-tokens."
+  },
+  "export": {
+    "CLOUDFLARE_API_TOKEN": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/cloudflare.json b/src/authsome/auth/bundled_providers/cloudflare.jsonc
similarity index 75%
rename from src/authsome/auth/bundled_providers/cloudflare.json
rename to src/authsome/auth/bundled_providers/cloudflare.jsonc
index 1900cd67..ca895b52 100644
--- a/src/authsome/auth/bundled_providers/cloudflare.json
+++ b/src/authsome/auth/bundled_providers/cloudflare.jsonc
@@ -1,3 +1,7 @@
+// Cloudflare
+// Cloudflare API token access for managing zones, DNS, Workers, and account resources.
+// auth: api_key | flow: api_key
+// Prefer scoped tokens over global API keys. Create at dash.cloudflare.com/profile/api-tokens.
 {
   "schema_version": 1,
   "name": "cloudflare",
@@ -19,3 +23,4 @@
     "CLOUDFLARE_API_TOKEN": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/confluence.json b/src/authsome/auth/bundled_providers/confluence.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/confluence.json
rename to src/authsome/auth/bundled_providers/confluence.jsonc
index d610f576..53bd8417 100644
--- a/src/authsome/auth/bundled_providers/confluence.json
+++ b/src/authsome/auth/bundled_providers/confluence.jsonc
@@ -1,3 +1,7 @@
+// Confluence
+// Confluence Cloud access for reading and writing pages, spaces, and content via the Confluence REST API.
+// auth: oauth2 | flow: pkce
+// Covered by the Atlassian OAuth provider; this standalone provider uses the Confluence REST API directly.
 {
   "schema_version": 1,
   "name": "confluence",
@@ -29,3 +33,4 @@
     "CONFLUENCE_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/discord.json b/src/authsome/auth/bundled_providers/discord.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/discord.json
rename to src/authsome/auth/bundled_providers/discord.jsonc
index f78bb104..8c6166bc 100644
--- a/src/authsome/auth/bundled_providers/discord.json
+++ b/src/authsome/auth/bundled_providers/discord.jsonc
@@ -1,3 +1,7 @@
+// Discord
+// Discord identity, guild, and messaging integrations over OAuth.
+// auth: oauth2 | flow: pkce
+// Scopes needed vary by bot — guilds.members.read requires privileged intent approval.
 {
   "schema_version": 1,
   "name": "discord",
@@ -27,3 +31,4 @@
     "DISCORD_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/dub.json b/src/authsome/auth/bundled_providers/dub.jsonc
similarity index 69%
rename from src/authsome/auth/bundled_providers/dub.json
rename to src/authsome/auth/bundled_providers/dub.jsonc
index 6d6cf1fc..e8d1d783 100644
--- a/src/authsome/auth/bundled_providers/dub.json
+++ b/src/authsome/auth/bundled_providers/dub.jsonc
@@ -1,3 +1,7 @@
+// Dub.co
+// Short links, conversion tracking, and link analytics from Dub.co.
+// auth: api_key | flow: api_key
+// API keys are workspace-level; generate at app.dub.co/settings/tokens.
 {
   "schema_version": 1,
   "name": "dub",
@@ -16,3 +20,4 @@
     "DUB_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/fireworks.jsonc b/src/authsome/auth/bundled_providers/fireworks.jsonc
new file mode 100644
index 00000000..b5e3715c
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/fireworks.jsonc
@@ -0,0 +1,24 @@
+// Fireworks AI
+// API key access to open-source and fine-tuned models via Fireworks AI.
+// auth: api_key | flow: api_key
+// OpenAI-compatible API. Keys are generated at fireworks.ai/account/api-keys.
+{
+  "schema_version": 1,
+  "name": "fireworks",
+  "display_name": "Fireworks AI",
+  "logo": "img.logo.dev/name/fireworks-ai",
+  "description": "Fireworks AI API key for fast inference on open-source and fine-tuned models.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.fireworks.ai/inference/v1",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "FIREWORKS_API_KEY",
+    "key_pattern_hint": "Fireworks AI keys are generated at fireworks.ai/account/api-keys."
+  },
+  "export": {
+    "FIREWORKS_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/g2.json b/src/authsome/auth/bundled_providers/g2.jsonc
similarity index 68%
rename from src/authsome/auth/bundled_providers/g2.json
rename to src/authsome/auth/bundled_providers/g2.jsonc
index f06d0c0d..d78a4c4c 100644
--- a/src/authsome/auth/bundled_providers/g2.json
+++ b/src/authsome/auth/bundled_providers/g2.jsonc
@@ -1,3 +1,7 @@
+// G2
+// Review, buyer intent, and marketplace data from G2.
+// auth: api_key | flow: api_key
+// G2 has two key types: public (read) and private (write). Use private only if needed.
 {
   "schema_version": 1,
   "name": "g2",
@@ -16,3 +20,4 @@
     "G2_API_TOKEN": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/github-mcp.jsonc b/src/authsome/auth/bundled_providers/github-mcp.jsonc
new file mode 100644
index 00000000..78b98f8c
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/github-mcp.jsonc
@@ -0,0 +1,28 @@
+// GitHub MCP
+// GitHub personal access token for the remote GitHub MCP server.
+// auth: api_key | flow: api_key
+// Distinct from the GitHub OAuth provider (github.jsonc) which uses PKCE/device-code.
+// This provider stores a fine-grained PAT injected as Bearer token at the MCP endpoint.
+// Prefer fine-grained tokens scoped to only the repos and permissions the agent needs.
+{
+  "schema_version": 1,
+  "name": "github-mcp",
+  "display_name": "GitHub MCP",
+  "logo": "img.logo.dev/name/github",
+  "description": "GitHub personal access token for the remote MCP server — enables agents to manage repos, issues, and PRs via MCP.",
+  "type": "mcp",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.githubcopilot.com/mcp",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "GITHUB_TOKEN",
+    "key_pattern": "^(ghp_|github_pat_)[A-Za-z0-9_]+$",
+    "key_pattern_hint": "GitHub tokens start with 'ghp_' (classic) or 'github_pat_' (fine-grained). Create one at github.com/settings/tokens."
+  },
+  "export": {
+    "GITHUB_TOKEN": "API_TOKEN",
+    "GH_TOKEN": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/github.json b/src/authsome/auth/bundled_providers/github.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/github.json
rename to src/authsome/auth/bundled_providers/github.jsonc
index ac42f72a..7d047a62 100644
--- a/src/authsome/auth/bundled_providers/github.json
+++ b/src/authsome/auth/bundled_providers/github.jsonc
@@ -1,3 +1,7 @@
+// GitHub
+// Connect GitHub to manage repositories, pull requests, users, and developer automation with vault-backed credentials.
+// auth: oauth2 | flow: pkce
+// Fine-grained PATs are preferred over classic tokens. Device-code flow is supported for headless envs.
 {
   "schema_version": 1,
   "name": "github",
@@ -31,3 +35,4 @@
   },
   "docs_url": "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens"
 }
+
diff --git a/src/authsome/auth/bundled_providers/gitlab.json b/src/authsome/auth/bundled_providers/gitlab.jsonc
similarity index 81%
rename from src/authsome/auth/bundled_providers/gitlab.json
rename to src/authsome/auth/bundled_providers/gitlab.jsonc
index 2022bd82..eb48042d 100644
--- a/src/authsome/auth/bundled_providers/gitlab.json
+++ b/src/authsome/auth/bundled_providers/gitlab.jsonc
@@ -1,3 +1,7 @@
+// GitLab
+// GitLab repositories, user data, and project automation over OAuth.
+// auth: oauth2 | flow: pkce
+// Scopes: 'api' covers full access; prefer granular scopes in production.
 {
   "schema_version": 1,
   "name": "gitlab",
@@ -29,3 +33,4 @@
     "GITLAB_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-admin.json b/src/authsome/auth/bundled_providers/google-admin.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-admin.json
rename to src/authsome/auth/bundled_providers/google-admin.jsonc
index bffdc3a7..44185767 100644
--- a/src/authsome/auth/bundled_providers/google-admin.json
+++ b/src/authsome/auth/bundled_providers/google-admin.jsonc
@@ -1,3 +1,7 @@
+// Google Admin
+// Google Workspace Admin access for managing users, groups, and organizational units via the Admin SDK.
+// auth: oauth2 | flow: pkce
+// Requires Google Workspace domain admin privileges; not available to personal Gmail accounts.
 {
   "schema_version": 1,
   "name": "google-admin",
@@ -27,3 +31,4 @@
     "GOOGLE_ADMIN_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-analytics.json b/src/authsome/auth/bundled_providers/google-analytics.jsonc
similarity index 81%
rename from src/authsome/auth/bundled_providers/google-analytics.json
rename to src/authsome/auth/bundled_providers/google-analytics.jsonc
index 43316e0e..925cb3e5 100644
--- a/src/authsome/auth/bundled_providers/google-analytics.json
+++ b/src/authsome/auth/bundled_providers/google-analytics.jsonc
@@ -1,3 +1,7 @@
+// Google Analytics
+// Google Analytics access for reading web analytics data via the Analytics Data API.
+// auth: oauth2 | flow: pkce
+// Scopes cover GA4; UA properties use different APIs and are deprecated.
 {
   "schema_version": 1,
   "name": "google-analytics",
@@ -26,3 +30,4 @@
     "GOOGLE_ANALYTICS_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-calendar.json b/src/authsome/auth/bundled_providers/google-calendar.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-calendar.json
rename to src/authsome/auth/bundled_providers/google-calendar.jsonc
index 94936e03..ae64a6b4 100644
--- a/src/authsome/auth/bundled_providers/google-calendar.json
+++ b/src/authsome/auth/bundled_providers/google-calendar.jsonc
@@ -1,3 +1,7 @@
+// Google Calendar
+// Google Calendar access for reading and managing calendar events via the Calendar API.
+// auth: oauth2 | flow: pkce
+// The 'calendar' scope grants full read/write; 'calendar.readonly' is safer for read-only agents.
 {
   "schema_version": 1,
   "name": "google-calendar",
@@ -26,3 +30,4 @@
     "GOOGLE_CALENDAR_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-chat.json b/src/authsome/auth/bundled_providers/google-chat.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/google-chat.json
rename to src/authsome/auth/bundled_providers/google-chat.jsonc
index f78af240..b25c8052 100644
--- a/src/authsome/auth/bundled_providers/google-chat.json
+++ b/src/authsome/auth/bundled_providers/google-chat.jsonc
@@ -1,3 +1,7 @@
+// Google Chat
+// Google Chat access for sending and managing messages and spaces via the Chat API.
+// auth: oauth2 | flow: pkce
+// Google Chat API requires a Service Account or Workspace domain; consumer accounts have limited access.
 {
   "schema_version": 1,
   "name": "google-chat",
@@ -26,3 +30,4 @@
     "GOOGLE_CHAT_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-classroom.json b/src/authsome/auth/bundled_providers/google-classroom.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-classroom.json
rename to src/authsome/auth/bundled_providers/google-classroom.jsonc
index dfba1ed9..7d79c0e1 100644
--- a/src/authsome/auth/bundled_providers/google-classroom.json
+++ b/src/authsome/auth/bundled_providers/google-classroom.jsonc
@@ -1,3 +1,7 @@
+// Google Classroom
+// Google Classroom access for managing courses, assignments, and student rosters via the Classroom API.
+// auth: oauth2 | flow: pkce
+// Requires an approved Google Workspace for Education account; consumer accounts are blocked.
 {
   "schema_version": 1,
   "name": "google-classroom",
@@ -27,3 +31,4 @@
     "GOOGLE_CLASSROOM_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-docs.json b/src/authsome/auth/bundled_providers/google-docs.jsonc
similarity index 80%
rename from src/authsome/auth/bundled_providers/google-docs.json
rename to src/authsome/auth/bundled_providers/google-docs.jsonc
index 59f3c2d9..810d2b4d 100644
--- a/src/authsome/auth/bundled_providers/google-docs.json
+++ b/src/authsome/auth/bundled_providers/google-docs.jsonc
@@ -1,3 +1,7 @@
+// Google Docs
+// Google Docs access for reading and editing documents via the Docs API.
+// auth: oauth2 | flow: pkce
+// 'drive.file' scope is narrower and preferred; 'documents' grants access to all docs.
 {
   "schema_version": 1,
   "name": "google-docs",
@@ -26,3 +30,4 @@
     "GOOGLE_DOCS_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-drive.json b/src/authsome/auth/bundled_providers/google-drive.jsonc
similarity index 81%
rename from src/authsome/auth/bundled_providers/google-drive.json
rename to src/authsome/auth/bundled_providers/google-drive.jsonc
index 4e9ca82b..8a0e1fa9 100644
--- a/src/authsome/auth/bundled_providers/google-drive.json
+++ b/src/authsome/auth/bundled_providers/google-drive.jsonc
@@ -1,3 +1,7 @@
+// Google Drive
+// Google Drive access for managing files and folders via the Drive API.
+// auth: oauth2 | flow: pkce
+// Use 'drive.file' scope to limit access to files created/opened by the app.
 {
   "schema_version": 1,
   "name": "google-drive",
@@ -26,3 +30,4 @@
     "GOOGLE_DRIVE_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-forms.json b/src/authsome/auth/bundled_providers/google-forms.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-forms.json
rename to src/authsome/auth/bundled_providers/google-forms.jsonc
index 7b83d535..b2bc5ef1 100644
--- a/src/authsome/auth/bundled_providers/google-forms.json
+++ b/src/authsome/auth/bundled_providers/google-forms.jsonc
@@ -1,3 +1,7 @@
+// Google Forms
+// Google Forms access for creating forms and reading responses via the Forms API.
+// auth: oauth2 | flow: pkce
+// Forms API gives access to form structure and responses; requires OAuth — service accounts not supported.
 {
   "schema_version": 1,
   "name": "google-forms",
@@ -27,3 +31,4 @@
     "GOOGLE_FORMS_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-gmail.json b/src/authsome/auth/bundled_providers/google-gmail.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-gmail.json
rename to src/authsome/auth/bundled_providers/google-gmail.jsonc
index 944621a0..13bc7054 100644
--- a/src/authsome/auth/bundled_providers/google-gmail.json
+++ b/src/authsome/auth/bundled_providers/google-gmail.jsonc
@@ -1,3 +1,7 @@
+// Gmail
+// Gmail access for reading, composing, and managing email via the Gmail API.
+// auth: oauth2 | flow: pkce
+// Use granular scopes (e.g. gmail.send, gmail.readonly) instead of the full gmail scope in production.
 {
   "schema_version": 1,
   "name": "google-gmail",
@@ -26,3 +30,4 @@
     "GMAIL_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-meet.json b/src/authsome/auth/bundled_providers/google-meet.jsonc
similarity index 80%
rename from src/authsome/auth/bundled_providers/google-meet.json
rename to src/authsome/auth/bundled_providers/google-meet.jsonc
index 589d5f96..9135c91a 100644
--- a/src/authsome/auth/bundled_providers/google-meet.json
+++ b/src/authsome/auth/bundled_providers/google-meet.jsonc
@@ -1,3 +1,7 @@
+// Google Meet
+// Google Meet access for creating and managing video meeting spaces via the Meet REST API.
+// auth: oauth2 | flow: pkce
+// Google Meet API is separate from Calendar; requires Meet license in Workspace.
 {
   "schema_version": 1,
   "name": "google-meet",
@@ -26,3 +30,4 @@
     "GOOGLE_MEET_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-photos.json b/src/authsome/auth/bundled_providers/google-photos.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-photos.json
rename to src/authsome/auth/bundled_providers/google-photos.jsonc
index 83e582b7..ae3a9570 100644
--- a/src/authsome/auth/bundled_providers/google-photos.json
+++ b/src/authsome/auth/bundled_providers/google-photos.jsonc
@@ -1,3 +1,7 @@
+// Google Photos
+// Google Photos access for reading and managing photo libraries via the Photos Library API.
+// auth: oauth2 | flow: pkce
+// Photos API only accesses media uploaded by the app unless the user grants broader access.
 {
   "schema_version": 1,
   "name": "google-photos",
@@ -26,3 +30,4 @@
     "GOOGLE_PHOTOS_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-search-console.json b/src/authsome/auth/bundled_providers/google-search-console.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-search-console.json
rename to src/authsome/auth/bundled_providers/google-search-console.jsonc
index e4050cbc..699c98b0 100644
--- a/src/authsome/auth/bundled_providers/google-search-console.json
+++ b/src/authsome/auth/bundled_providers/google-search-console.jsonc
@@ -1,3 +1,7 @@
+// Google Search Console
+// Google Search Console access for reading search analytics and sitemaps via the Search Console API.
+// auth: oauth2 | flow: pkce
+// Only works for verified domain owners; property must be added in Search Console.
 {
   "schema_version": 1,
   "name": "google-search-console",
@@ -26,3 +30,4 @@
     "GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-sheets.json b/src/authsome/auth/bundled_providers/google-sheets.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-sheets.json
rename to src/authsome/auth/bundled_providers/google-sheets.jsonc
index 4e5c3239..d7f6ab5d 100644
--- a/src/authsome/auth/bundled_providers/google-sheets.json
+++ b/src/authsome/auth/bundled_providers/google-sheets.jsonc
@@ -1,3 +1,7 @@
+// Google Sheets
+// Google Sheets access for reading and editing spreadsheets via the Sheets API.
+// auth: oauth2 | flow: pkce
+// 'spreadsheets' scope grants full read/write; 'spreadsheets.readonly' is safer for read-only agents.
 {
   "schema_version": 1,
   "name": "google-sheets",
@@ -26,3 +30,4 @@
     "GOOGLE_SHEETS_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-slides.json b/src/authsome/auth/bundled_providers/google-slides.jsonc
similarity index 83%
rename from src/authsome/auth/bundled_providers/google-slides.json
rename to src/authsome/auth/bundled_providers/google-slides.jsonc
index 8a9b98ed..47005f3b 100644
--- a/src/authsome/auth/bundled_providers/google-slides.json
+++ b/src/authsome/auth/bundled_providers/google-slides.jsonc
@@ -1,3 +1,7 @@
+// Google Slides
+// Google Slides access for reading and editing presentations via the Slides API.
+// auth: oauth2 | flow: pkce
+// 'presentations' scope grants full read/write.
 {
   "schema_version": 1,
   "name": "google-slides",
@@ -26,3 +30,4 @@
     "GOOGLE_SLIDES_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-tasks.json b/src/authsome/auth/bundled_providers/google-tasks.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-tasks.json
rename to src/authsome/auth/bundled_providers/google-tasks.jsonc
index dafdc1f4..dcf8c7e6 100644
--- a/src/authsome/auth/bundled_providers/google-tasks.json
+++ b/src/authsome/auth/bundled_providers/google-tasks.jsonc
@@ -1,3 +1,7 @@
+// Google Tasks
+// Google Tasks access for reading and managing task lists and tasks via the Tasks API.
+// auth: oauth2 | flow: pkce
+// Tasks API only accesses the authenticated user's task lists; no sharing across users.
 {
   "schema_version": 1,
   "name": "google-tasks",
@@ -26,3 +30,4 @@
     "GOOGLE_TASKS_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-vertex-ai.json b/src/authsome/auth/bundled_providers/google-vertex-ai.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google-vertex-ai.json
rename to src/authsome/auth/bundled_providers/google-vertex-ai.jsonc
index 0a5c316e..2a4c7d06 100644
--- a/src/authsome/auth/bundled_providers/google-vertex-ai.json
+++ b/src/authsome/auth/bundled_providers/google-vertex-ai.jsonc
@@ -1,3 +1,7 @@
+// Vertex AI
+// Google Vertex AI access for generative models, embeddings, and ML pipelines via the Vertex AI API.
+// auth: oauth2 | flow: pkce
+// Requires Google Cloud project with Vertex AI API enabled; use service account in production.
 {
   "schema_version": 1,
   "name": "google-vertex-ai",
@@ -26,3 +30,4 @@
     "VERTEX_AI_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google-youtube.json b/src/authsome/auth/bundled_providers/google-youtube.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/google-youtube.json
rename to src/authsome/auth/bundled_providers/google-youtube.jsonc
index 993b3a0e..edad2687 100644
--- a/src/authsome/auth/bundled_providers/google-youtube.json
+++ b/src/authsome/auth/bundled_providers/google-youtube.jsonc
@@ -1,3 +1,7 @@
+// YouTube
+// YouTube Data API access for managing channels, videos, playlists, and comments.
+// auth: oauth2 | flow: pkce
+// 'youtube.readonly' scope is sufficient for most read operations; full 'youtube' scope required for uploads.
 {
   "schema_version": 1,
   "name": "google-youtube",
@@ -26,3 +30,4 @@
     "YOUTUBE_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/google.json b/src/authsome/auth/bundled_providers/google.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/google.json
rename to src/authsome/auth/bundled_providers/google.jsonc
index 44536892..885eca26 100644
--- a/src/authsome/auth/bundled_providers/google.json
+++ b/src/authsome/auth/bundled_providers/google.jsonc
@@ -1,3 +1,7 @@
+// Google
+// Google identity and Google API access with OAuth-backed credentials.
+// auth: oauth2 | flow: pkce
+// Root Google OAuth provider; prefer the service-specific providers for narrower scopes.
 {
   "schema_version": 1,
   "name": "google",
@@ -25,3 +29,4 @@
     "GOOGLE_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/groq.jsonc b/src/authsome/auth/bundled_providers/groq.jsonc
new file mode 100644
index 00000000..abda1d01
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/groq.jsonc
@@ -0,0 +1,25 @@
+// Groq
+// API key access to Groq LPU inference — ultra-low latency completions.
+// auth: api_key | flow: api_key
+// Keys begin with "gsk_" and are generated at console.groq.com/keys.
+{
+  "schema_version": 1,
+  "name": "groq",
+  "display_name": "Groq",
+  "logo": "img.logo.dev/name/groq",
+  "description": "Groq API key for ultra-fast LPU inference via the OpenAI-compatible completions API.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.groq.com",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "GROQ_API_KEY",
+    "key_pattern": "^gsk_[A-Za-z0-9]+$",
+    "key_pattern_hint": "Groq API keys start with 'gsk_'. Generate one at console.groq.com/keys."
+  },
+  "export": {
+    "GROQ_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/hubspot.json b/src/authsome/auth/bundled_providers/hubspot.jsonc
similarity index 82%
rename from src/authsome/auth/bundled_providers/hubspot.json
rename to src/authsome/auth/bundled_providers/hubspot.jsonc
index f9042e3c..f958e4d4 100644
--- a/src/authsome/auth/bundled_providers/hubspot.json
+++ b/src/authsome/auth/bundled_providers/hubspot.jsonc
@@ -1,3 +1,7 @@
+// HubSpot
+// CRM contacts, companies, deals, owners, and HubSpot workflow data.
+// auth: oauth2 | flow: pkce
+// Scopes are granular per HubSpot hub (CRM, CMS, Marketing). Add only the hubs your agent needs.
 {
   "schema_version": 1,
   "name": "hubspot",
@@ -30,3 +34,4 @@
     "HUBSPOT_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/hunter.json b/src/authsome/auth/bundled_providers/hunter.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/hunter.json
rename to src/authsome/auth/bundled_providers/hunter.jsonc
index be59139b..d6bcbab1 100644
--- a/src/authsome/auth/bundled_providers/hunter.json
+++ b/src/authsome/auth/bundled_providers/hunter.jsonc
@@ -1,3 +1,7 @@
+// Hunter
+// Email discovery and verification data for outreach workflows.
+// auth: api_key | flow: api_key
+// Hunter.io keys are account-level; generate at hunter.io/api-keys.
 {
   "schema_version": 1,
   "name": "hunter",
@@ -16,3 +20,4 @@
     "HUNTER_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/instantly.json b/src/authsome/auth/bundled_providers/instantly.jsonc
similarity index 69%
rename from src/authsome/auth/bundled_providers/instantly.json
rename to src/authsome/auth/bundled_providers/instantly.jsonc
index 70d79826..8c43640a 100644
--- a/src/authsome/auth/bundled_providers/instantly.json
+++ b/src/authsome/auth/bundled_providers/instantly.jsonc
@@ -1,3 +1,7 @@
+// Instantly
+// Outbound email campaign and lead management automation.
+// auth: api_key | flow: api_key
+// API keys are workspace-level; generate at app.instantly.ai/app/settings/integrations.
 {
   "schema_version": 1,
   "name": "instantly",
@@ -16,3 +20,4 @@
     "INSTANTLY_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/intercom.json b/src/authsome/auth/bundled_providers/intercom.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/intercom.json
rename to src/authsome/auth/bundled_providers/intercom.jsonc
index 01dc7fe0..ff538f05 100644
--- a/src/authsome/auth/bundled_providers/intercom.json
+++ b/src/authsome/auth/bundled_providers/intercom.jsonc
@@ -1,3 +1,7 @@
+// Intercom
+// Customer conversations, contacts, and support automation APIs.
+// auth: api_key | flow: api_key
+// OAuth scopes cover workspace inbox, contacts, and conversations.
 {
   "schema_version": 1,
   "name": "intercom",
@@ -16,3 +20,4 @@
     "INTERCOM_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/jira.json b/src/authsome/auth/bundled_providers/jira.jsonc
similarity index 77%
rename from src/authsome/auth/bundled_providers/jira.json
rename to src/authsome/auth/bundled_providers/jira.jsonc
index 17abdda3..b70e4f5c 100644
--- a/src/authsome/auth/bundled_providers/jira.json
+++ b/src/authsome/auth/bundled_providers/jira.jsonc
@@ -1,3 +1,7 @@
+// Jira
+// Jira Cloud access for reading and managing issues, projects, and workflows via the Jira REST API.
+// auth: oauth2 | flow: pkce
+// Covered by the Atlassian OAuth provider; this standalone provider uses the Jira REST API directly.
 {
   "schema_version": 1,
   "name": "jira",
@@ -28,3 +32,4 @@
     "JIRA_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/keywords-everywhere.json b/src/authsome/auth/bundled_providers/keywords-everywhere.jsonc
similarity index 73%
rename from src/authsome/auth/bundled_providers/keywords-everywhere.json
rename to src/authsome/auth/bundled_providers/keywords-everywhere.jsonc
index e0d6daa1..9ad3b49f 100644
--- a/src/authsome/auth/bundled_providers/keywords-everywhere.json
+++ b/src/authsome/auth/bundled_providers/keywords-everywhere.jsonc
@@ -1,3 +1,7 @@
+// Keywords Everywhere
+// Keyword volume, CPC, and SEO metrics for search workflows.
+// auth: api_key | flow: api_key
+// API keys are account-level; available only on paid plans.
 {
   "schema_version": 1,
   "name": "keywords-everywhere",
@@ -16,3 +20,4 @@
     "KEYWORDS_EVERYWHERE_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/klaviyo-oauth.json b/src/authsome/auth/bundled_providers/klaviyo-oauth.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/klaviyo-oauth.json
rename to src/authsome/auth/bundled_providers/klaviyo-oauth.jsonc
index 5f4fffe0..3b85646e 100644
--- a/src/authsome/auth/bundled_providers/klaviyo-oauth.json
+++ b/src/authsome/auth/bundled_providers/klaviyo-oauth.jsonc
@@ -1,3 +1,7 @@
+// Klaviyo (OAuth)
+// OAuth access for Klaviyo app integrations and account APIs.
+// auth: oauth2 | flow: pkce
+// Klaviyo OAuth2 provider; use this instead of klaviyo.jsonc when user-level OAuth is needed.
 {
   "schema_version": 1,
   "name": "klaviyo-oauth",
@@ -24,3 +28,4 @@
   },
   "docs_url": "https://developers.klaviyo.com/en/docs/manage_your_app"
 }
+
diff --git a/src/authsome/auth/bundled_providers/klaviyo.json b/src/authsome/auth/bundled_providers/klaviyo.jsonc
similarity index 67%
rename from src/authsome/auth/bundled_providers/klaviyo.json
rename to src/authsome/auth/bundled_providers/klaviyo.jsonc
index 62669ff9..12eeb589 100644
--- a/src/authsome/auth/bundled_providers/klaviyo.json
+++ b/src/authsome/auth/bundled_providers/klaviyo.jsonc
@@ -1,3 +1,7 @@
+// Klaviyo
+// Klaviyo profiles, campaigns, and marketing automation API access.
+// auth: api_key | flow: api_key
+// Private API keys are account-level (full access); prefer OAuth or scoped keys in production.
 {
   "schema_version": 1,
   "name": "klaviyo",
@@ -16,3 +20,4 @@
     "KLAVIYO_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/lemlist.json b/src/authsome/auth/bundled_providers/lemlist.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/lemlist.json
rename to src/authsome/auth/bundled_providers/lemlist.jsonc
index 0001056a..7a896374 100644
--- a/src/authsome/auth/bundled_providers/lemlist.json
+++ b/src/authsome/auth/bundled_providers/lemlist.jsonc
@@ -1,3 +1,7 @@
+// Lemlist
+// Cold outreach campaigns, leads, and email engagement workflows.
+// auth: api_key | flow: api_key
+// API keys are team-level; generate at app.lemlist.com/settings.
 {
   "schema_version": 1,
   "name": "lemlist",
@@ -16,3 +20,4 @@
     "LEMLIST_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/linear-mcp.jsonc b/src/authsome/auth/bundled_providers/linear-mcp.jsonc
new file mode 100644
index 00000000..65613862
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/linear-mcp.jsonc
@@ -0,0 +1,27 @@
+// Linear MCP
+// Linear API key for the remote Linear MCP server.
+// auth: api_key | flow: api_key
+// Distinct from the Linear OAuth provider (linear.jsonc) which uses PKCE.
+// This provider stores a personal API key injected as Bearer token at mcp.linear.app.
+// Keys are generated at linear.app/settings/api.
+{
+  "schema_version": 1,
+  "name": "linear-mcp",
+  "display_name": "Linear MCP",
+  "logo": "img.logo.dev/name/linear",
+  "description": "Linear API key for the remote MCP server — enables agents to manage issues, projects, and teams via MCP.",
+  "type": "mcp",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://mcp.linear.app",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "LINEAR_API_KEY",
+    "key_pattern": "^lin_api_[A-Za-z0-9]+$",
+    "key_pattern_hint": "Linear API keys start with 'lin_api_'. Generate one at linear.app/settings/api."
+  },
+  "export": {
+    "LINEAR_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/linear.json b/src/authsome/auth/bundled_providers/linear.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/linear.json
rename to src/authsome/auth/bundled_providers/linear.jsonc
index 662914f7..d7f87773 100644
--- a/src/authsome/auth/bundled_providers/linear.json
+++ b/src/authsome/auth/bundled_providers/linear.jsonc
@@ -1,3 +1,7 @@
+// Linear
+// Issues, teams, projects, and product operations through Linear.
+// auth: oauth2 | flow: pkce
+// PKCE OAuth — no client secret needed in public clients. Scopes: 'read' and 'write'.
 {
   "schema_version": 1,
   "name": "linear",
@@ -25,3 +29,4 @@
     "LINEAR_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/linkedin-browser.json b/src/authsome/auth/bundled_providers/linkedin-browser.jsonc
similarity index 67%
rename from src/authsome/auth/bundled_providers/linkedin-browser.json
rename to src/authsome/auth/bundled_providers/linkedin-browser.jsonc
index bfc75b59..59ade2e8 100644
--- a/src/authsome/auth/bundled_providers/linkedin-browser.json
+++ b/src/authsome/auth/bundled_providers/linkedin-browser.jsonc
@@ -1,10 +1,15 @@
+// LinkedIn — Browser Session
+// Extracts the li_at session cookie from a real LinkedIn browser session.
+// auth: browser | flow: browser
+// JSESSIONID is mapped to the csrf-token header required by LinkedIn's API.
+// ttl_from_cookie: li_at — expiry is read from the cookie itself, not a fixed TTL.
 {
   "schema_version": 1,
   "name": "linkedin-browser",
-  "display_name": "LinkedIn \u2014 Browser Session",
+  "display_name": "LinkedIn — Browser Session",
   "logo": "img.logo.dev/name/linkedin",
   "description": "LinkedIn browser-session credentials for authenticated web workflows.",
-  "type": "app",
+  "type": "browser",
   "auth_type": "browser",
   "flow": "browser",
   "api_url": "regex:^(www\\.linkedin\\.com|linkedin\\.com)",
diff --git a/src/authsome/auth/bundled_providers/livestorm.json b/src/authsome/auth/bundled_providers/livestorm.jsonc
similarity index 69%
rename from src/authsome/auth/bundled_providers/livestorm.json
rename to src/authsome/auth/bundled_providers/livestorm.jsonc
index 4f93942a..742929dc 100644
--- a/src/authsome/auth/bundled_providers/livestorm.json
+++ b/src/authsome/auth/bundled_providers/livestorm.jsonc
@@ -1,3 +1,7 @@
+// Livestorm
+// Webinar, event, registrant, and attendee data from Livestorm.
+// auth: api_key | flow: api_key
+// API keys are account-level; generate at app.livestorm.co/settings/integrations.
 {
   "schema_version": 1,
   "name": "livestorm",
@@ -16,3 +20,4 @@
     "LIVESTORM_API_TOKEN": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/mailchimp.json b/src/authsome/auth/bundled_providers/mailchimp.jsonc
similarity index 67%
rename from src/authsome/auth/bundled_providers/mailchimp.json
rename to src/authsome/auth/bundled_providers/mailchimp.jsonc
index 1eeed2b6..9a8efaa1 100644
--- a/src/authsome/auth/bundled_providers/mailchimp.json
+++ b/src/authsome/auth/bundled_providers/mailchimp.jsonc
@@ -1,3 +1,7 @@
+// Mailchimp
+// Audience, campaign, and marketing automation APIs from Mailchimp.
+// auth: api_key | flow: api_key
+// OAuth gives workspace-level access; the data center (us1, us2, etc.) must be included in API URLs.
 {
   "schema_version": 1,
   "name": "mailchimp",
@@ -16,3 +20,4 @@
     "MAILCHIMP_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/mention-me.json b/src/authsome/auth/bundled_providers/mention-me.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/mention-me.json
rename to src/authsome/auth/bundled_providers/mention-me.jsonc
index c65ca266..f48d0491 100644
--- a/src/authsome/auth/bundled_providers/mention-me.json
+++ b/src/authsome/auth/bundled_providers/mention-me.jsonc
@@ -1,3 +1,7 @@
+// Mention Me
+// Referral marketing campaigns, contacts, and Mention Me data access.
+// auth: api_key | flow: api_key
+// API keys are account-level; contact Mention Me support to obtain one.
 {
   "schema_version": 1,
   "name": "mention-me",
@@ -16,3 +20,4 @@
     "MENTIONME_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/microsoft-calendar.json b/src/authsome/auth/bundled_providers/microsoft-calendar.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/microsoft-calendar.json
rename to src/authsome/auth/bundled_providers/microsoft-calendar.jsonc
index 4c3b9026..0846d733 100644
--- a/src/authsome/auth/bundled_providers/microsoft-calendar.json
+++ b/src/authsome/auth/bundled_providers/microsoft-calendar.jsonc
@@ -1,3 +1,7 @@
+// Outlook Calendar
+// Outlook Calendar access for reading and managing calendar events and schedules via Microsoft Graph.
+// auth: oauth2 | flow: pkce
+// Uses delegated OAuth with Microsoft identity. 'Calendars.ReadWrite' scope covers all calendar operations.
 {
   "schema_version": 1,
   "name": "microsoft-calendar",
@@ -26,3 +30,4 @@
     "MICROSOFT_CALENDAR_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/microsoft-outlook.json b/src/authsome/auth/bundled_providers/microsoft-outlook.jsonc
similarity index 80%
rename from src/authsome/auth/bundled_providers/microsoft-outlook.json
rename to src/authsome/auth/bundled_providers/microsoft-outlook.jsonc
index 1a8af83c..ced19dea 100644
--- a/src/authsome/auth/bundled_providers/microsoft-outlook.json
+++ b/src/authsome/auth/bundled_providers/microsoft-outlook.jsonc
@@ -1,3 +1,7 @@
+// Microsoft Outlook
+// Microsoft Outlook access for reading, sending, and managing email via Microsoft Graph.
+// auth: oauth2 | flow: pkce
+// Uses delegated OAuth with Microsoft identity. 'Mail.ReadWrite' scope covers full mailbox access.
 {
   "schema_version": 1,
   "name": "microsoft-outlook",
@@ -28,3 +32,4 @@
     "MICROSOFT_OUTLOOK_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/microsoft-word.json b/src/authsome/auth/bundled_providers/microsoft-word.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/microsoft-word.json
rename to src/authsome/auth/bundled_providers/microsoft-word.jsonc
index e47009c0..1fc45bf5 100644
--- a/src/authsome/auth/bundled_providers/microsoft-word.json
+++ b/src/authsome/auth/bundled_providers/microsoft-word.jsonc
@@ -1,3 +1,7 @@
+// Microsoft Word
+// Microsoft Word document access for reading and editing .docx files stored in OneDrive and SharePoint via Microsoft Graph.
+// auth: oauth2 | flow: pkce
+// Uses delegated OAuth with Microsoft identity. 'Files.ReadWrite' covers OneDrive/Word files.
 {
   "schema_version": 1,
   "name": "microsoft-word",
@@ -27,3 +31,4 @@
     "MICROSOFT_WORD_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/microsoft.json b/src/authsome/auth/bundled_providers/microsoft.jsonc
similarity index 81%
rename from src/authsome/auth/bundled_providers/microsoft.json
rename to src/authsome/auth/bundled_providers/microsoft.jsonc
index b8fd3876..39b17b81 100644
--- a/src/authsome/auth/bundled_providers/microsoft.json
+++ b/src/authsome/auth/bundled_providers/microsoft.jsonc
@@ -1,3 +1,7 @@
+// Microsoft
+// Microsoft Graph access for mail, calendars, files, tasks, and identity.
+// auth: oauth2 | flow: pkce
+// Root Microsoft OAuth provider; prefer service-specific providers for narrower scopes.
 {
   "schema_version": 1,
   "name": "microsoft",
@@ -29,3 +33,4 @@
     "MICROSOFT_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/mistral.jsonc b/src/authsome/auth/bundled_providers/mistral.jsonc
new file mode 100644
index 00000000..96e4cd7f
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/mistral.jsonc
@@ -0,0 +1,24 @@
+// Mistral AI
+// API key access to Mistral models via la Plateforme.
+// auth: api_key | flow: api_key
+// Keys are generated at console.mistral.ai. Standard Authorization Bearer scheme.
+{
+  "schema_version": 1,
+  "name": "mistral",
+  "display_name": "Mistral AI",
+  "logo": "img.logo.dev/name/mistral-ai",
+  "description": "Mistral AI API key for chat completions and embedding models via la Plateforme.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.mistral.ai",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "MISTRAL_API_KEY",
+    "key_pattern_hint": "Mistral API keys are generated at console.mistral.ai."
+  },
+  "export": {
+    "MISTRAL_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/notion_dcr.json b/src/authsome/auth/bundled_providers/notion-mcp.jsonc
similarity index 66%
rename from src/authsome/auth/bundled_providers/notion_dcr.json
rename to src/authsome/auth/bundled_providers/notion-mcp.jsonc
index 1bb1fc61..95dd7de6 100644
--- a/src/authsome/auth/bundled_providers/notion_dcr.json
+++ b/src/authsome/auth/bundled_providers/notion-mcp.jsonc
@@ -1,10 +1,15 @@
+// Notion MCP
+// Notion MCP OAuth access using dynamic client registration.
+// auth: oauth2 | flow: dcr_pkce
+// Distinct from the Notion OAuth provider (notion.jsonc) which uses the standard Notion API.
+// DCR handles public OAuth without requiring a pre-registered client.
 {
   "schema_version": 1,
-  "name": "notion_dcr",
-  "display_name": "Notion (DCR)",
+  "name": "notion-mcp",
+  "display_name": "Notion MCP",
   "logo": "img.logo.dev/name/notion",
   "description": "Notion MCP OAuth access using dynamic client registration.",
-  "type": "app",
+  "type": "mcp",
   "auth_type": "oauth2",
   "flow": "dcr_pkce",
   "api_url": "mcp.notion.com",
diff --git a/src/authsome/auth/bundled_providers/notion.json b/src/authsome/auth/bundled_providers/notion.jsonc
similarity index 77%
rename from src/authsome/auth/bundled_providers/notion.json
rename to src/authsome/auth/bundled_providers/notion.jsonc
index 5e135394..c6fad164 100644
--- a/src/authsome/auth/bundled_providers/notion.json
+++ b/src/authsome/auth/bundled_providers/notion.jsonc
@@ -1,3 +1,7 @@
+// Notion
+// Notion workspace content and integration access over OAuth.
+// auth: oauth2 | flow: pkce
+// Notion OAuth uses HTTP Basic auth at the token endpoint — set authorization_method: basic.
 {
   "schema_version": 1,
   "name": "notion",
@@ -23,3 +27,4 @@
     "NOTION_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/openai.json b/src/authsome/auth/bundled_providers/openai.jsonc
similarity index 75%
rename from src/authsome/auth/bundled_providers/openai.json
rename to src/authsome/auth/bundled_providers/openai.jsonc
index 0e148112..577ebd9f 100644
--- a/src/authsome/auth/bundled_providers/openai.json
+++ b/src/authsome/auth/bundled_providers/openai.jsonc
@@ -1,3 +1,7 @@
+// OpenAI
+// OpenAI API keys for model, assistant, and platform automation.
+// auth: api_key | flow: api_key
+// Keys start with 'sk-'; project-scoped keys (sk-proj-*) are preferred for production use.
 {
   "schema_version": 1,
   "name": "openai",
@@ -19,3 +23,4 @@
     "OPENAI_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/openrouter.jsonc b/src/authsome/auth/bundled_providers/openrouter.jsonc
new file mode 100644
index 00000000..583ea608
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/openrouter.jsonc
@@ -0,0 +1,26 @@
+// OpenRouter
+// Unified API key to route requests across 200+ LLM providers.
+// auth: api_key | flow: api_key
+// Keys begin with "sk-or-v1-". The API is OpenAI-compatible (same endpoint shape).
+// Use OPENAI_BASE_URL=https://openrouter.ai/api/v1 alongside OPENROUTER_API_KEY.
+{
+  "schema_version": 1,
+  "name": "openrouter",
+  "display_name": "OpenRouter",
+  "logo": "img.logo.dev/name/openrouter",
+  "description": "OpenRouter API key for unified access to 200+ LLMs via an OpenAI-compatible API.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://openrouter.ai/api/v1",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "OPENROUTER_API_KEY",
+    "key_pattern": "^sk-or-v1-[A-Za-z0-9]+$",
+    "key_pattern_hint": "OpenRouter keys start with 'sk-or-v1-'. Generate one at openrouter.ai/keys."
+  },
+  "export": {
+    "OPENROUTER_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/optimizely.json b/src/authsome/auth/bundled_providers/optimizely.jsonc
similarity index 69%
rename from src/authsome/auth/bundled_providers/optimizely.json
rename to src/authsome/auth/bundled_providers/optimizely.jsonc
index 129fc64b..60f29d80 100644
--- a/src/authsome/auth/bundled_providers/optimizely.json
+++ b/src/authsome/auth/bundled_providers/optimizely.jsonc
@@ -1,3 +1,7 @@
+// Optimizely
+// Experimentation, feature flags, and Optimizely platform APIs.
+// auth: api_key | flow: api_key
+// API keys are personal tokens; generate at app.optimizely.com/v2/profile#api-keys.
 {
   "schema_version": 1,
   "name": "optimizely",
@@ -16,3 +20,4 @@
     "OPTIMIZELY_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/perplexity.jsonc b/src/authsome/auth/bundled_providers/perplexity.jsonc
new file mode 100644
index 00000000..2c307f72
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/perplexity.jsonc
@@ -0,0 +1,25 @@
+// Perplexity AI
+// API key access to Perplexity's online LLMs with real-time web search.
+// auth: api_key | flow: api_key
+// OpenAI-compatible API. Keys begin with "pplx-" and are generated at perplexity.ai/settings/api.
+{
+  "schema_version": 1,
+  "name": "perplexity",
+  "display_name": "Perplexity AI",
+  "logo": "img.logo.dev/name/perplexity",
+  "description": "Perplexity AI API key for online LLM inference with real-time web search grounding.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.perplexity.ai",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "PERPLEXITY_API_KEY",
+    "key_pattern": "^pplx-[A-Za-z0-9]+$",
+    "key_pattern_hint": "Perplexity keys start with 'pplx-'. Generate one at perplexity.ai/settings/api."
+  },
+  "export": {
+    "PERPLEXITY_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/postiz.json b/src/authsome/auth/bundled_providers/postiz.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/postiz.json
rename to src/authsome/auth/bundled_providers/postiz.jsonc
index 1f6829d7..1f6c7fdf 100644
--- a/src/authsome/auth/bundled_providers/postiz.json
+++ b/src/authsome/auth/bundled_providers/postiz.jsonc
@@ -1,3 +1,7 @@
+// Postiz
+// Social publishing and Postiz API access through device authorization.
+// auth: oauth2 | flow: device_code
+// Postiz is self-hosted; device-code flow uses a custom JSON body format (not standard OAuth2 form).
 {
   "schema_version": 1,
   "name": "postiz",
@@ -24,3 +28,4 @@
   },
   "docs_url": "https://docs.postiz.com/public-api/oauth"
 }
+
diff --git a/src/authsome/auth/bundled_providers/postmark.json b/src/authsome/auth/bundled_providers/postmark.jsonc
similarity index 67%
rename from src/authsome/auth/bundled_providers/postmark.json
rename to src/authsome/auth/bundled_providers/postmark.jsonc
index d3c224f9..a313c1bc 100644
--- a/src/authsome/auth/bundled_providers/postmark.json
+++ b/src/authsome/auth/bundled_providers/postmark.jsonc
@@ -1,3 +1,7 @@
+// Postmark
+// Transactional email sending and server token access from Postmark.
+// auth: api_key | flow: api_key
+// Server tokens are per-server; account tokens have full access. Use server tokens for production.
 {
   "schema_version": 1,
   "name": "postmark",
@@ -16,3 +20,4 @@
     "POSTMARK_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/reddit.json b/src/authsome/auth/bundled_providers/reddit.jsonc
similarity index 82%
rename from src/authsome/auth/bundled_providers/reddit.json
rename to src/authsome/auth/bundled_providers/reddit.jsonc
index a21af147..028c7352 100644
--- a/src/authsome/auth/bundled_providers/reddit.json
+++ b/src/authsome/auth/bundled_providers/reddit.jsonc
@@ -1,3 +1,7 @@
+// Reddit
+// Authenticate with Reddit API.
+// auth: oauth2 | flow: pkce
+// Reddit OAuth uses 'duration=permanent' for long-lived tokens; access tokens expire after 1 hour but are refreshable.
 {
   "schema_version": 1,
   "name": "reddit",
@@ -23,3 +27,4 @@
     "REDDIT_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/resend.json b/src/authsome/auth/bundled_providers/resend.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/resend.json
rename to src/authsome/auth/bundled_providers/resend.jsonc
index c3ba52cb..c58f97c3 100644
--- a/src/authsome/auth/bundled_providers/resend.json
+++ b/src/authsome/auth/bundled_providers/resend.jsonc
@@ -1,3 +1,7 @@
+// Resend
+// Email sending, domains, audiences, and Resend API automation.
+// auth: api_key | flow: api_key
+// API keys are workspace-level; generate at resend.com/api-keys.
 {
   "schema_version": 1,
   "name": "resend",
@@ -16,3 +20,4 @@
     "RESEND_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/rewardful.json b/src/authsome/auth/bundled_providers/rewardful.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/rewardful.json
rename to src/authsome/auth/bundled_providers/rewardful.jsonc
index 94bc69fa..033772a5 100644
--- a/src/authsome/auth/bundled_providers/rewardful.json
+++ b/src/authsome/auth/bundled_providers/rewardful.jsonc
@@ -1,3 +1,7 @@
+// Rewardful
+// Affiliate and referral tracking data from Rewardful.
+// auth: api_key | flow: api_key
+// API keys are account-level; generate at app.getrewardful.com/settings/developer.
 {
   "schema_version": 1,
   "name": "rewardful",
@@ -16,3 +20,4 @@
     "REWARDFUL_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/savvycal.json b/src/authsome/auth/bundled_providers/savvycal.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/savvycal.json
rename to src/authsome/auth/bundled_providers/savvycal.jsonc
index 845e67af..6ae16539 100644
--- a/src/authsome/auth/bundled_providers/savvycal.json
+++ b/src/authsome/auth/bundled_providers/savvycal.jsonc
@@ -1,3 +1,7 @@
+// SavvyCal
+// Scheduling links, events, and availability workflows from SavvyCal.
+// auth: api_key | flow: api_key
+// API keys are user-level; generate at savvycal.com/personal/api.
 {
   "schema_version": 1,
   "name": "savvycal",
@@ -16,3 +20,4 @@
     "SAVVYCAL_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/semrush.json b/src/authsome/auth/bundled_providers/semrush.jsonc
similarity index 67%
rename from src/authsome/auth/bundled_providers/semrush.json
rename to src/authsome/auth/bundled_providers/semrush.jsonc
index eb1e7757..5140fbcc 100644
--- a/src/authsome/auth/bundled_providers/semrush.json
+++ b/src/authsome/auth/bundled_providers/semrush.jsonc
@@ -1,3 +1,7 @@
+// SEMrush
+// SEO, competitive research, and search analytics from Semrush.
+// auth: api_key | flow: api_key
+// API keys are account-level and tied to SEMrush usage units; generate at semrush.com/my_reports/.
 {
   "schema_version": 1,
   "name": "semrush",
@@ -16,3 +20,4 @@
     "SEMRUSH_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/sendgrid.json b/src/authsome/auth/bundled_providers/sendgrid.jsonc
similarity index 73%
rename from src/authsome/auth/bundled_providers/sendgrid.json
rename to src/authsome/auth/bundled_providers/sendgrid.jsonc
index f8fc45e8..19c47205 100644
--- a/src/authsome/auth/bundled_providers/sendgrid.json
+++ b/src/authsome/auth/bundled_providers/sendgrid.jsonc
@@ -1,3 +1,7 @@
+// SendGrid
+// SendGrid email delivery, templates, and account API access.
+// auth: api_key | flow: api_key
+// API keys can be scoped per-permission; prefer scoped keys over full-access keys.
 {
   "schema_version": 1,
   "name": "sendgrid",
@@ -17,3 +21,4 @@
   },
   "docs_url": "https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys"
 }
+
diff --git a/src/authsome/auth/bundled_providers/sentry-mcp.jsonc b/src/authsome/auth/bundled_providers/sentry-mcp.jsonc
new file mode 100644
index 00000000..89801f3c
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/sentry-mcp.jsonc
@@ -0,0 +1,25 @@
+// Sentry MCP
+// Sentry auth token for the remote Sentry MCP server.
+// auth: api_key | flow: api_key
+// The token is injected as Bearer token when connecting to mcp.sentry.io.
+// Create a token at sentry.io/settings/account/api/auth-tokens/ with the scopes your agent needs.
+{
+  "schema_version": 1,
+  "name": "sentry-mcp",
+  "display_name": "Sentry MCP",
+  "logo": "img.logo.dev/name/sentry",
+  "description": "Sentry auth token for the remote MCP server — enables agents to query errors, issues, and releases via MCP.",
+  "type": "mcp",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://mcp.sentry.io",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "SENTRY_AUTH_TOKEN",
+    "key_pattern_hint": "Sentry auth tokens are created at sentry.io/settings/account/api/auth-tokens/."
+  },
+  "export": {
+    "SENTRY_AUTH_TOKEN": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/slack-mcp.jsonc b/src/authsome/auth/bundled_providers/slack-mcp.jsonc
new file mode 100644
index 00000000..273f6891
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/slack-mcp.jsonc
@@ -0,0 +1,27 @@
+// Slack MCP
+// Slack bot token for the remote Slack MCP server.
+// auth: api_key | flow: api_key
+// Distinct from the Slack OAuth provider (slack.jsonc) which uses PKCE OAuth2.
+// This provider stores a bot token injected as Bearer token at the MCP endpoint.
+// Bot tokens start with "xoxb-" and are issued when you install a Slack app to a workspace.
+{
+  "schema_version": 1,
+  "name": "slack-mcp",
+  "display_name": "Slack MCP",
+  "logo": "img.logo.dev/name/slack",
+  "description": "Slack bot token for the remote MCP server — enables agents to read channels, post messages, and manage workspaces via MCP.",
+  "type": "mcp",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://mcp.slack.com",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "SLACK_BOT_TOKEN",
+    "key_pattern": "^xoxb-[A-Za-z0-9-]+$",
+    "key_pattern_hint": "Slack bot tokens start with 'xoxb-'. Install a Slack app to your workspace to get one."
+  },
+  "export": {
+    "SLACK_BOT_TOKEN": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/slack.json b/src/authsome/auth/bundled_providers/slack.jsonc
similarity index 78%
rename from src/authsome/auth/bundled_providers/slack.json
rename to src/authsome/auth/bundled_providers/slack.jsonc
index 769df877..49a02dd2 100644
--- a/src/authsome/auth/bundled_providers/slack.json
+++ b/src/authsome/auth/bundled_providers/slack.jsonc
@@ -1,3 +1,7 @@
+// Slack
+// Slack workspace channels, chat, and collaboration workflows over OAuth.
+// auth: oauth2 | flow: pkce
+// OAuth v2 with granular bot scopes; xoxb- tokens are bot tokens, xoxp- are user tokens.
 {
   "schema_version": 1,
   "name": "slack",
@@ -25,3 +29,4 @@
     "SLACK_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/stripe-mcp.jsonc b/src/authsome/auth/bundled_providers/stripe-mcp.jsonc
new file mode 100644
index 00000000..cccc3616
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/stripe-mcp.jsonc
@@ -0,0 +1,27 @@
+// Stripe MCP
+// Stripe secret key for the official Stripe remote MCP server.
+// auth: api_key | flow: api_key
+// The key is injected as Bearer token when connecting to mcp.stripe.com.
+// Use a restricted key with only the permissions your agent needs.
+// Secret keys begin with "sk_live_" or "sk_test_"; keys are in the Stripe dashboard.
+{
+  "schema_version": 1,
+  "name": "stripe-mcp",
+  "display_name": "Stripe MCP",
+  "logo": "img.logo.dev/name/stripe",
+  "description": "Stripe secret key for the remote MCP server — enables agents to manage payments, customers, and subscriptions via MCP.",
+  "type": "mcp",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://mcp.stripe.com",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "STRIPE_SECRET_KEY",
+    "key_pattern": "^(sk_live_|sk_test_)[A-Za-z0-9]+$",
+    "key_pattern_hint": "Stripe keys start with 'sk_live_' or 'sk_test_'. Prefer a restricted key scoped to only what the agent needs."
+  },
+  "export": {
+    "STRIPE_SECRET_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/todoist.json b/src/authsome/auth/bundled_providers/todoist.jsonc
similarity index 77%
rename from src/authsome/auth/bundled_providers/todoist.json
rename to src/authsome/auth/bundled_providers/todoist.jsonc
index d61df2da..5691ccb6 100644
--- a/src/authsome/auth/bundled_providers/todoist.json
+++ b/src/authsome/auth/bundled_providers/todoist.jsonc
@@ -1,3 +1,7 @@
+// Todoist
+// Todoist access for managing tasks, projects, and labels via the Todoist REST API.
+// auth: oauth2 | flow: pkce
+// OAuth scopes: 'data:read_write,data:delete' for full access; use 'data:read' for read-only agents.
 {
   "schema_version": 1,
   "name": "todoist",
@@ -25,3 +29,4 @@
     "TODOIST_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/together.jsonc b/src/authsome/auth/bundled_providers/together.jsonc
new file mode 100644
index 00000000..7700f43e
--- /dev/null
+++ b/src/authsome/auth/bundled_providers/together.jsonc
@@ -0,0 +1,24 @@
+// Together AI
+// API key access to open-source models via Together AI's inference platform.
+// auth: api_key | flow: api_key
+// OpenAI-compatible API. Keys are generated at api.together.ai/settings/api-keys.
+{
+  "schema_version": 1,
+  "name": "together",
+  "display_name": "Together AI",
+  "logo": "img.logo.dev/name/together-ai",
+  "description": "Together AI API key for fast inference on open-source LLMs via an OpenAI-compatible API.",
+  "type": "llm",
+  "auth_type": "api_key",
+  "flow": "api_key",
+  "api_url": "https://api.together.ai/v1",
+  "api_key": {
+    "header_name": "Authorization",
+    "header_prefix": "Bearer",
+    "env_var": "TOGETHER_API_KEY",
+    "key_pattern_hint": "Together AI keys are generated at api.together.ai/settings/api-keys."
+  },
+  "export": {
+    "TOGETHER_API_KEY": "API_TOKEN"
+  }
+}
diff --git a/src/authsome/auth/bundled_providers/tolt.json b/src/authsome/auth/bundled_providers/tolt.jsonc
similarity index 69%
rename from src/authsome/auth/bundled_providers/tolt.json
rename to src/authsome/auth/bundled_providers/tolt.jsonc
index 85e4ae6c..d7779fac 100644
--- a/src/authsome/auth/bundled_providers/tolt.json
+++ b/src/authsome/auth/bundled_providers/tolt.jsonc
@@ -1,3 +1,7 @@
+// Tolt
+// Affiliate tracking, partner data, and referral program automation.
+// auth: api_key | flow: api_key
+// API keys are workspace-level; generate in the Tolt dashboard settings.
 {
   "schema_version": 1,
   "name": "tolt",
@@ -16,3 +20,4 @@
     "TOLT_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/typeform.json b/src/authsome/auth/bundled_providers/typeform.jsonc
similarity index 72%
rename from src/authsome/auth/bundled_providers/typeform.json
rename to src/authsome/auth/bundled_providers/typeform.jsonc
index 78312e23..96705b68 100644
--- a/src/authsome/auth/bundled_providers/typeform.json
+++ b/src/authsome/auth/bundled_providers/typeform.jsonc
@@ -1,3 +1,7 @@
+// Typeform
+// Forms, responses, and Typeform workspace automation.
+// auth: api_key | flow: api_key
+// OAuth scopes cover form responses, workspaces, and webhooks.
 {
   "schema_version": 1,
   "name": "typeform",
@@ -16,3 +20,4 @@
     "TYPEFORM_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/wistia.json b/src/authsome/auth/bundled_providers/wistia.jsonc
similarity index 68%
rename from src/authsome/auth/bundled_providers/wistia.json
rename to src/authsome/auth/bundled_providers/wistia.jsonc
index cb0dfdbe..0dfe7471 100644
--- a/src/authsome/auth/bundled_providers/wistia.json
+++ b/src/authsome/auth/bundled_providers/wistia.jsonc
@@ -1,3 +1,7 @@
+// Wistia
+// Video hosting, media analytics, and Wistia account APIs.
+// auth: api_key | flow: api_key
+// API password tokens are account-level; generate at app.wistia.com/settings/api-password.
 {
   "schema_version": 1,
   "name": "wistia",
@@ -16,3 +20,4 @@
     "WISTIA_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/x-browser.json b/src/authsome/auth/bundled_providers/x-browser.jsonc
similarity index 70%
rename from src/authsome/auth/bundled_providers/x-browser.json
rename to src/authsome/auth/bundled_providers/x-browser.jsonc
index 09790d54..7d8324c7 100644
--- a/src/authsome/auth/bundled_providers/x-browser.json
+++ b/src/authsome/auth/bundled_providers/x-browser.jsonc
@@ -1,10 +1,15 @@
+// X (Twitter) — Browser Session
+// Extracts the auth_token session cookie from a real X/Twitter browser session.
+// auth: browser | flow: browser
+// ct0 cookie is mapped to x-csrf-token header required by X's API.
+// Works against both x.com and legacy twitter.com API domains.
 {
   "schema_version": 1,
   "name": "x-browser",
-  "display_name": "X (Twitter) \u2014 Browser Session",
+  "display_name": "X (Twitter) — Browser Session",
   "logo": "img.logo.dev/name/x",
   "description": "X browser-session credentials for authenticated web workflows.",
-  "type": "app",
+  "type": "browser",
   "auth_type": "browser",
   "flow": "browser",
   "api_url": "regex:^(api\\.twitter\\.com|api\\.x\\.com|x\\.com|twitter\\.com)",
diff --git a/src/authsome/auth/bundled_providers/x.json b/src/authsome/auth/bundled_providers/x.jsonc
similarity index 79%
rename from src/authsome/auth/bundled_providers/x.json
rename to src/authsome/auth/bundled_providers/x.jsonc
index 71a6d7e5..6c9a5191 100644
--- a/src/authsome/auth/bundled_providers/x.json
+++ b/src/authsome/auth/bundled_providers/x.jsonc
@@ -1,3 +1,7 @@
+// X (Twitter)
+// X OAuth access for posts, user data, and social automation.
+// auth: oauth2 | flow: pkce
+// X OAuth 2.0 with PKCE. Use fine-grained scopes — 'tweet.read', 'tweet.write', 'users.read' etc.
 {
   "schema_version": 1,
   "name": "x",
@@ -28,3 +32,4 @@
     "X_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/zapier.json b/src/authsome/auth/bundled_providers/zapier.jsonc
similarity index 67%
rename from src/authsome/auth/bundled_providers/zapier.json
rename to src/authsome/auth/bundled_providers/zapier.jsonc
index 2b1f550c..017d5aea 100644
--- a/src/authsome/auth/bundled_providers/zapier.json
+++ b/src/authsome/auth/bundled_providers/zapier.jsonc
@@ -1,3 +1,7 @@
+// Zapier
+// Zapier platform API access for automation and connected workflows.
+// auth: api_key | flow: api_key
+// OAuth for Zapier integrations; requires a registered Zapier app with a client ID/secret.
 {
   "schema_version": 1,
   "name": "zapier",
@@ -16,3 +20,4 @@
     "ZAPIER_API_KEY": "API_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/bundled_providers/zoom.json b/src/authsome/auth/bundled_providers/zoom.jsonc
similarity index 82%
rename from src/authsome/auth/bundled_providers/zoom.json
rename to src/authsome/auth/bundled_providers/zoom.jsonc
index d42f8f03..b9aa7f02 100644
--- a/src/authsome/auth/bundled_providers/zoom.json
+++ b/src/authsome/auth/bundled_providers/zoom.jsonc
@@ -1,3 +1,7 @@
+// Zoom
+// Zoom access for creating and managing meetings, users, and recordings via the Zoom API.
+// auth: oauth2 | flow: pkce
+// OAuth for Zoom meetings, webinars, and recording management.
 {
   "schema_version": 1,
   "name": "zoom",
@@ -28,3 +32,4 @@
     "ZOOM_ACCESS_TOKEN": "ACCESS_TOKEN"
   }
 }
+
diff --git a/src/authsome/auth/models/enums.py b/src/authsome/auth/models/enums.py
index 4cab2b4a..87aa874c 100644
--- a/src/authsome/auth/models/enums.py
+++ b/src/authsome/auth/models/enums.py
@@ -37,6 +37,7 @@ class ProviderType(StrEnum):
     APP = "app"
     LLM = "llm"
     MCP = "mcp"
+    BROWSER = "browser"
 
 
 class ExportFormat(StrEnum):