claudecode-linter 2.1.150 → 2.1.153

package/contracts/settings.schema.json

@@ -1,13 +1,13 @@
 {
-	"extractedFromClaudeCodeVersion": "2.1.146",
-	"extractedAt": "2026-05-22T08:16:43.683Z",
+	"extractedFromClaudeCodeVersion": "2.1.153",
+	"extractedAt": "2026-05-28T01:01:28.673Z",
 	"schema": {
 		"$schema": "https://json-schema.org/draft/2020-12/schema",
 		"title": "Claude Code settings.json",
 		"type": "object",
 		"properties": {
 			"$schema": {
-				"const": "pXq",
+				"const": "https://json.schemastore.org/claude-code-settings.json",
 				"description": "JSON Schema reference for Claude Code settings"
 			},
 			"apiKeyHelper": {
@@ -78,6 +78,48 @@
 				"type": "boolean",
 				"description": "Whether file picker should respect .gitignore files (default: true). Note: .ignore files are always respected."
 			},
+			"breakReminder": {
+				"type": "object",
+				"properties": {
+					"enabled": {
+						"type": "boolean",
+						"description": "Show a friendly nudge after sustained continuous use (default false). Must be true for the reminder to fire."
+					},
+					"intervalMinutes": {
+						"type": "number",
+						"description": "Minutes of continuous use before the reminder fires (default 120). Re-fires every interval until you take a break."
+					},
+					"breakThresholdMinutes": {
+						"type": "number",
+						"description": "Minutes of inactivity that count as a break and reset the timer (default 15)"
+					},
+					"message": {
+						"type": "string",
+						"description": "Custom reminder text. Leave unset for a rotating set of friendly nudges."
+					}
+				},
+				"description": "@internal Opt-in break reminder. When enabled, shows a dismissible nudge after sustained continuous use. Never blocks — just a friendly heads-up."
+			},
+			"quietHours": {
+				"type": "object",
+				"properties": {
+					"enabled": {
+						"type": "boolean",
+						"description": "Show a one-time nudge when you start or keep using the CLI inside your quiet-hours window (default false)."
+					},
+					"start": {
+						"type": "string",
+						"pattern": "^([01]?\\d|2[0-3]):[0-5]\\d$",
+						"description": "Start of the quiet-hours window, 24-hour local time \"HH:MM\"."
+					},
+					"end": {
+						"type": "string",
+						"pattern": "^([01]?\\d|2[0-3]):[0-5]\\d$",
+						"description": "End of the quiet-hours window, 24-hour local time \"HH:MM\". May be earlier than start for an overnight range."
+					}
+				},
+				"description": "@internal Opt-in quiet hours. When enabled, shows a single soft nudge per session while inside the configured local-time window. Never blocks."
+			},
 			"cleanupPeriodDays": {
 				"type": "number",
 				"description": "Number of days to retain chat transcripts before automatic cleanup (default: 30). Minimum 1. Use a large value for long retention; use --no-session-persistence to disable transcript writes entirely."
@@ -531,6 +573,14 @@
 				"type": "boolean",
 				"description": "Disable Remote Control (claude.ai/code, `claude remote-control`, `--remote-control`/`--rc`, auto-start, and the in-session toggle). Typically set in managed settings."
 			},
+			"disableWorkflows": {
+				"type": "boolean",
+				"description": "@internal Disable the Workflows feature (also via CLAUDE_CODE_DISABLE_WORKFLOWS)."
+			},
+			"enableWorkflows": {
+				"type": "boolean",
+				"description": "Enable or disable the Workflows feature for this user. Unset = default by plan once the feature is available."
+			},
 			"disableSkillShellExecution": {
 				"type": "boolean",
 				"description": "Disable inline shell execution in skills and custom slash commands from user, project, or plugin sources. Commands are replaced with a placeholder instead of being run."
@@ -568,6 +618,10 @@
 				"type": "boolean",
 				"description": "When true (and set in managed settings), allowedMcpServers is only read from managed settings. deniedMcpServers still merges from all sources, so users can deny servers for themselves. Users can still add their own MCP servers, but only the admin-defined allowlist applies."
 			},
+			"allowAllClaudeAiMcps": {
+				"type": "boolean",
+				"description": "When true (and set in managed settings), claude.ai cloud MCP connectors load alongside managed-mcp.json instead of being suppressed by its exclusive-control lockdown. Default off preserves the lockdown. Read from managed settings only."
+			},
 			"strictPluginOnlyCustomization": {
 				"anyOf": [
 					{
@@ -710,6 +764,10 @@
 												"type": "string"
 											},
 											"description": "Directories to include via git sparse-checkout (cone mode). Use for monorepos where the marketplace lives in a subdirectory. Example: [\".claude-plugin\", \"plugins\"]. If omitted, the full repository is cloned."
+										},
+										"skipLfs": {
+											"type": "boolean",
+											"description": "Skip Git LFS smudge during clone and update (sets GIT_LFS_SKIP_SMUDGE=1) so LFS pointer files stay as pointers instead of downloading their content. Use for marketplaces hosted in repos with large LFS objects."
 										}
 									},
 									"required": [
@@ -741,6 +799,10 @@
 												"type": "string"
 											},
 											"description": "Directories to include via git sparse-checkout (cone mode). Use for monorepos where the marketplace lives in a subdirectory. Example: [\".claude-plugin\", \"plugins\"]. If omitted, the full repository is cloned."
+										},
+										"skipLfs": {
+											"type": "boolean",
+											"description": "Skip Git LFS smudge during clone and update (sets GIT_LFS_SKIP_SMUDGE=1) so LFS pointer files stay as pointers instead of downloading their content. Use for marketplaces hosted in repos with large LFS objects."
 										}
 									},
 									"required": [
@@ -1112,6 +1174,10 @@
 										"type": "string"
 									},
 									"description": "Directories to include via git sparse-checkout (cone mode). Use for monorepos where the marketplace lives in a subdirectory. Example: [\".claude-plugin\", \"plugins\"]. If omitted, the full repository is cloned."
+								},
+								"skipLfs": {
+									"type": "boolean",
+									"description": "Skip Git LFS smudge during clone and update (sets GIT_LFS_SKIP_SMUDGE=1) so LFS pointer files stay as pointers instead of downloading their content. Use for marketplaces hosted in repos with large LFS objects."
 								}
 							},
 							"required": [
@@ -1143,6 +1209,10 @@
 										"type": "string"
 									},
 									"description": "Directories to include via git sparse-checkout (cone mode). Use for monorepos where the marketplace lives in a subdirectory. Example: [\".claude-plugin\", \"plugins\"]. If omitted, the full repository is cloned."
+								},
+								"skipLfs": {
+									"type": "boolean",
+									"description": "Skip Git LFS smudge during clone and update (sets GIT_LFS_SKIP_SMUDGE=1) so LFS pointer files stay as pointers instead of downloading their content. Use for marketplaces hosted in repos with large LFS objects."
 								}
 							},
 							"required": [
@@ -1500,6 +1570,10 @@
 										"type": "string"
 									},
 									"description": "Directories to include via git sparse-checkout (cone mode). Use for monorepos where the marketplace lives in a subdirectory. Example: [\".claude-plugin\", \"plugins\"]. If omitted, the full repository is cloned."
+								},
+								"skipLfs": {
+									"type": "boolean",
+									"description": "Skip Git LFS smudge during clone and update (sets GIT_LFS_SKIP_SMUDGE=1) so LFS pointer files stay as pointers instead of downloading their content. Use for marketplaces hosted in repos with large LFS objects."
 								}
 							},
 							"required": [
@@ -1531,6 +1605,10 @@
 										"type": "string"
 									},
 									"description": "Directories to include via git sparse-checkout (cone mode). Use for monorepos where the marketplace lives in a subdirectory. Example: [\".claude-plugin\", \"plugins\"]. If omitted, the full repository is cloned."
+								},
+								"skipLfs": {
+									"type": "boolean",
+									"description": "Skip Git LFS smudge during clone and update (sets GIT_LFS_SKIP_SMUDGE=1) so LFS pointer files stay as pointers instead of downloading their content. Use for marketplaces hosted in repos with large LFS objects."
 								}
 							},
 							"required": [
@@ -1836,6 +1914,13 @@
 				},
 				"description": "Enterprise blocklist of marketplace sources. When set in managed settings, these exact sources are blocked from being added as marketplaces. The check happens BEFORE downloading, so blocked sources never touch the filesystem."
 			},
+			"pluginSuggestionMarketplaces": {
+				"type": "array",
+				"items": {
+					"type": "string"
+				},
+				"description": "Marketplace names whose plugins may surface as contextual install suggestions (relevance-based tips), in addition to the official marketplace. Only honored when set in managed settings (policy scope); the key is ignored in user, project, and local settings. A name only takes effect when the marketplace is registered on the machine AND its registered source is also declared in managed settings, either as the extraKnownMarketplaces entry for that name or as an entry of strictKnownMarketplaces. A marketplace registered from a different source under an allowlisted name is ignored."
+			},
 			"forceLoginMethod": {
 				"enum": [
 					"claudeai",
@@ -2328,12 +2413,16 @@
 			},
 			"showThinkingSummaries": {
 				"type": "boolean",
-				"description": "Show thinking summaries in the transcript view (ctrl+o). Default: false."
+				"description": "Request API-side thinking summaries and show them in the conversation and in the transcript view (ctrl+o). Set explicitly to override the default for your install."
 			},
 			"skipDangerousModePermissionPrompt": {
 				"type": "boolean",
 				"description": "Whether the user has accepted the bypass permissions mode dialog"
 			},
+			"skipWorkflowUsageWarning": {
+				"type": "boolean",
+				"description": "@internal Whether the user has accepted the multi-agent workflow usage warning. Until set, auto permission mode prompts before running a workflow."
+			},
 			"disableAutoMode": {
 				"enum": [
 					"disable"

package/contracts/skill-frontmatter.schema.json

@@ -1,6 +1,6 @@
 {
-	"extractedFromClaudeCodeVersion": "2.1.146",
-	"extractedAt": "2026-05-22T08:49:59.762Z",
+	"extractedFromClaudeCodeVersion": "2.1.153",
+	"extractedAt": "2026-05-28T01:01:28.675Z",
 	"schema": {
 		"$schema": "https://json-schema.org/draft/2020-12/schema",
 		"title": "Claude Code SKILL.md frontmatter",
@@ -84,6 +84,60 @@
 				],
 				"description": "Tools available to the model while this file is active. Comma-separated string or YAML list."
 			},
+			"disallowed-tools": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Tools removed from the model while this file is active. Comma-separated string or YAML list. Cleared when the user sends the next message."
+			},
+			"disallowedTools": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Canonical (normalized) alias of `disallowed-tools`."
+			},
 			"argument-hint": {
 				"anyOf": [
 					{

package/dist/contracts.js

@@ -1,5 +1,5 @@
 // Auto-generated from contracts/claude-code-contracts.json
-// Claude Code v2.1.150 — extracted 2026-05-23T07:05:23.158Z
+// Claude Code v2.1.153 — extracted 2026-05-28T01:01:24.865Z
 // Do not edit manually. Run: npm run generate-contracts
 export const TOOLS = new Set([
     "Agent",
@@ -56,6 +56,7 @@ export const HOOK_EVENTS = new Set([
     "ElicitationResult",
     "FileChanged",
     "InstructionsLoaded",
+    "MessageDisplay",
     "Notification",
     "PermissionDenied",
     "PermissionRequest",
@@ -249,11 +250,13 @@ export const SETTINGS_USER_FIELDS = new Set([
     "disableBackgroundAgents",
     "disableRemoteControl",
     "disableSkillShellExecution",
+    "disableWorkflows",
     "disabledMcpjsonServers",
     "doneMeansMerged",
     "editorMode",
     "effortLevel",
     "enableAllProjectMcpServers",
+    "enableWorkflows",
     "enabledMcpjsonServers",
     "enabledPlugins",
     "env",
@@ -283,6 +286,7 @@ export const SETTINGS_USER_FIELDS = new Set([
     "permissions",
     "plansDirectory",
     "pluginConfigs",
+    "pluginSuggestionMarketplaces",
     "pluginTrustMessage",
     "policyHelper",
     "prUrlTemplate",
@@ -306,6 +310,7 @@ export const SETTINGS_USER_FIELDS = new Set([
     "skipAutoPermissionPrompt",
     "skipDangerousModePermissionPrompt",
     "skipWebFetchPreflight",
+    "skipWorkflowUsageWarning",
     "spinnerTipsEnabled",
     "spinnerTipsOverride",
     "spinnerVerbs",

package/dist/discovery.js

@@ -205,6 +205,25 @@ function discoverInDirectory(dir) {
     for (const f of monitors) {
         artifacts.push({ filePath: f, artifactType: "monitors-json" });
     }
+    // .claude-plugin/marketplace.json — schemastore-only artifact.
+    const marketplace = join(dir, ".claude-plugin", "marketplace.json");
+    if (existsSync(marketplace)) {
+        artifacts.push({ filePath: marketplace, artifactType: "marketplace-json" });
+    }
+    // keybindings.json — usually at ~/.claude/keybindings.json (user scope),
+    // but also picked up at project root if present. schemastore-only artifact.
+    for (const candidate of [
+        join(dir, "keybindings.json"),
+        join(dir, ".claude", "keybindings.json"),
+    ]) {
+        if (existsSync(candidate)) {
+            artifacts.push({
+                filePath: candidate,
+                artifactType: "keybindings-json",
+                scope: detectScope(candidate),
+            });
+        }
+    }
     // Claude config files — settings
     for (const name of ["settings.json", "settings.local.json"]) {
         // Direct in dir (handles both ~/.claude/settings.json and project root)
@@ -316,6 +335,10 @@ function classifyFile(filePath) {
     const parent = basename(dirname(filePath));
     if (name === "plugin.json" && parent === ".claude-plugin")
         return "plugin-json";
+    if (name === "marketplace.json" && parent === ".claude-plugin")
+        return "marketplace-json";
+    if (name === "keybindings.json")
+        return "keybindings-json";
     if (name === "SKILL.md")
         return "skill-md";
     if (name === "hooks.json" && parent === "hooks")

package/dist/fixers/mcp-json.js

@@ -33,6 +33,12 @@ export const mcpJsonFixer = {
                             orderedServer[field] = serverObj[field];
                         }
                     }
+                    // gitea#7: URL-based servers with type:"http" rewrite to
+                    // "streamable-http" (the runtime transport is identical post-v2.1.146;
+                    // the rename avoids the legacy OAuth-probe code path).
+                    if (orderedServer.type === "http" && typeof orderedServer.url === "string") {
+                        orderedServer.type = "streamable-http";
+                    }
                     sortedServers[serverName] = orderedServer;
                 }
                 else {

package/dist/index.js

@@ -21,6 +21,8 @@ import { mcpJsonLinter } from "./linters/mcp-json.js";
 import { claudeMdLinter } from "./linters/claude-md.js";
 import { lspJsonLinter } from "./linters/lsp-json.js";
 import { monitorsJsonLinter } from "./linters/monitors-json.js";
+import { marketplaceJsonLinter } from "./linters/marketplace-json.js";
+import { keybindingsJsonLinter } from "./linters/keybindings-json.js";
 import { misplacedFileLinter, MISPLACED_FILE_RULES, } from "./linters/misplaced-file.js";
 import { pluginJsonFixer } from "./fixers/plugin-json.js";
 import { frontmatterFixer } from "./fixers/frontmatter.js";
@@ -38,6 +40,8 @@ import { MCP_JSON_RULES } from "./linters/mcp-json.js";
 import { CLAUDE_MD_RULES } from "./linters/claude-md.js";
 import { LSP_JSON_RULES } from "./linters/lsp-json.js";
 import { MONITORS_JSON_RULES } from "./linters/monitors-json.js";
+import { MARKETPLACE_JSON_RULES } from "./linters/marketplace-json.js";
+import { KEYBINDINGS_JSON_RULES } from "./linters/keybindings-json.js";
 const LINTERS = {
     "plugin-json": pluginJsonLinter,
     "skill-md": skillMdLinter,
@@ -49,6 +53,8 @@ const LINTERS = {
     "claude-md": claudeMdLinter,
     "lsp-json": lspJsonLinter,
     "monitors-json": monitorsJsonLinter,
+    "marketplace-json": marketplaceJsonLinter,
+    "keybindings-json": keybindingsJsonLinter,
     "misplaced-file": misplacedFileLinter,
 };
 const FIXERS = {
@@ -72,6 +78,8 @@ const ALL_RULES = [
     ...CLAUDE_MD_RULES,
     ...LSP_JSON_RULES,
     ...MONITORS_JSON_RULES,
+    ...MARKETPLACE_JSON_RULES,
+    ...KEYBINDINGS_JSON_RULES,
     ...MISPLACED_FILE_RULES,
 ];
 /**

package/dist/linters/agent-md.js

@@ -69,7 +69,9 @@ const RULES = [
     { id: "agent-md/permission-mode-valid", defaultSeverity: "warning" },
     { id: "agent-md/effort-valid", defaultSeverity: "warning" },
     { id: "agent-md/max-turns-valid", defaultSeverity: "warning" },
-    { id: "agent-md/color-required", defaultSeverity: "warning" },
+    // agent-md/color-required removed in gitea#3 — Claude Code marks `color`
+    // as `.optional()` and `@internal`. The remaining `color-valid` rule still
+    // enforces the value set when an author opts in.
     { id: "agent-md/color-valid", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-present", defaultSeverity: "error" },
     { id: "agent-md/system-prompt-length", defaultSeverity: "warning" },
@@ -186,12 +188,19 @@ export const agentMdLinter = {
                 push(diag(config, filePath, "agent-md/max-turns-valid", "warning", `"maxTurns" must be a positive integer (got ${JSON.stringify(mt)})`));
             }
         }
-        // color
-        if (!("color" in fm.data) || typeof fm.data.color !== "string") {
-            push(diag(config, filePath, "agent-md/color-required", "warning", '"color" is required in frontmatter'));
-        }
-        else if (!AGENT_COLORS.has(fm.data.color)) {
-            push(diag(config, filePath, "agent-md/color-valid", "warning", `"color" must be one of: ${[...AGENT_COLORS].join(", ")} (got "${fm.data.color}")`));
+        // color — optional per Claude Code's agent frontmatter Zod schema
+        // (`color: hW().optional().describe("@internal — display color in the
+        // agents UI")`). Only validate the value if the user set one; never
+        // require it. The `color-required` rule (gitea#3) is kept on disk for
+        // users who explicitly opted in via .claudecode-lint.yaml, but defaults
+        // to off because requiring an @internal display field misled users.
+        if ("color" in fm.data) {
+            if (typeof fm.data.color !== "string") {
+                push(diag(config, filePath, "agent-md/color-valid", "warning", '"color" must be a string when set'));
+            }
+            else if (!AGENT_COLORS.has(fm.data.color)) {
+                push(diag(config, filePath, "agent-md/color-valid", "warning", `"color" must be one of: ${[...AGENT_COLORS].join(", ")} (got "${fm.data.color}")`));
+            }
         }
         // Frontmatter keys: only flag cross-artifact misplacement. A key valid
         // for a *different* markdown artifact (e.g. a skill-only key on an

package/dist/linters/keybindings-json.js

@@ -0,0 +1,53 @@
+import { formatAjvError, loadKeybindingsSchema, summarizeErrors, } from "../plugin-schema.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+export const KEYBINDINGS_JSON_RULES = [
+    { id: "keybindings-json/valid-json", defaultSeverity: "error" },
+    { id: "keybindings-json/schema-valid", defaultSeverity: "error" },
+];
+/**
+ * Validate `~/.claude/keybindings.json` (or per-project `keybindings.json`)
+ * against the schemastore.org curated schema. As with marketplace.json,
+ * there is no Zod source for keybindings in the Claude Code bundle —
+ * schemastore is the sole authoritative shape we have.
+ */
+export const keybindingsJsonLinter = {
+    artifactType: "keybindings-json",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => {
+            if (d)
+                diagnostics.push(d);
+        };
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            push(diag(config, filePath, "keybindings-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (isRuleEnabled(config, "keybindings-json/schema-valid")) {
+            const compiled = loadKeybindingsSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        push(diag(config, filePath, "keybindings-json/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+function diag(config, filePath, ruleId, defaultSeverity, message) {
+    if (!isRuleEnabled(config, ruleId))
+        return null;
+    return {
+        rule: ruleId,
+        severity: getRuleSeverity(config, ruleId, defaultSeverity),
+        message,
+        file: filePath,
+    };
+}
+//# sourceMappingURL=keybindings-json.js.map

package/dist/linters/marketplace-json.js

@@ -0,0 +1,55 @@
+import { formatAjvError, loadMarketplaceSchema, summarizeErrors, } from "../plugin-schema.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+export const MARKETPLACE_JSON_RULES = [
+    { id: "marketplace-json/valid-json", defaultSeverity: "error" },
+    { id: "marketplace-json/schema-valid", defaultSeverity: "error" },
+];
+/**
+ * Validate `.claude-plugin/marketplace.json` against the schemastore.org
+ * curated schema. There's no Zod source for marketplace.json in the Claude
+ * Code bundle — schemastore is the sole authoritative shape we have.
+ *
+ * If the schemastore bundle isn't shipped with this install (unlikely;
+ * package.json includes it), the schema check silently skips.
+ */
+export const marketplaceJsonLinter = {
+    artifactType: "marketplace-json",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => {
+            if (d)
+                diagnostics.push(d);
+        };
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            push(diag(config, filePath, "marketplace-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (isRuleEnabled(config, "marketplace-json/schema-valid")) {
+            const compiled = loadMarketplaceSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        push(diag(config, filePath, "marketplace-json/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+function diag(config, filePath, ruleId, defaultSeverity, message) {
+    if (!isRuleEnabled(config, ruleId))
+        return null;
+    return {
+        rule: ruleId,
+        severity: getRuleSeverity(config, ruleId, defaultSeverity),
+        message,
+        file: filePath,
+    };
+}
+//# sourceMappingURL=marketplace-json.js.map

package/dist/linters/mcp-json.js

@@ -19,6 +19,7 @@ const RULES = [
     { id: "mcp-json/url-protocol", defaultSeverity: "warning" },
     { id: "mcp-json/url-valid", defaultSeverity: "error" },
     { id: "mcp-json/type-matches-transport", defaultSeverity: "warning" },
+    { id: "mcp-json/prefer-streamable-http", defaultSeverity: "warning" },
     { id: "mcp-json/command-args-split", defaultSeverity: "info" },
     { id: "mcp-json/args-array", defaultSeverity: "error" },
     { id: "mcp-json/env-object", defaultSeverity: "error" },
@@ -143,6 +144,13 @@ export const mcpJsonLinter = {
                 if ("type" in server && !HTTP_TRANSPORT_TYPES.has(server.type)) {
                     push(diag(config, filePath, "mcp-json/type-matches-transport", "warning", `Server "${name}" has URL but type is "${server.type}" (expected one of ${[...HTTP_TRANSPORT_TYPES].join(", ")})`, sp?.line, sp?.column));
                 }
+                // Prefer "streamable-http" over "http" for URL-based MCP servers.
+                // Per gitea#7: older Claude Code's "http" transport may trigger an
+                // OAuth metadata probe / DCR POST that "streamable-http" skips, and
+                // misbehaving upstream proxies can silently fail with "0 tools".
+                if (server.type === "http") {
+                    push(diag(config, filePath, "mcp-json/prefer-streamable-http", "warning", `Server "${name}" uses type "http" — prefer "streamable-http" to avoid OAuth probe edge cases on some upstream proxies`, sp?.line, sp?.column));
+                }
             }
             // stdio server checks
             if (hasCommand && !hasUrl) {

package/dist/linters/plugin-json.js

@@ -22,6 +22,7 @@ const RULES = [
     { id: "plugin-json/keywords-no-duplicates", defaultSeverity: "warning" },
     { id: "plugin-json/no-unknown-fields", defaultSeverity: "info" },
     { id: "plugin-json/license-spdx", defaultSeverity: "info" },
+    { id: "plugin-json/no-inline-mcp-servers", defaultSeverity: "warning" },
 ];
 function findKeyPosition(content, key) {
     const re = new RegExp(`"${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"\\s*:`);
@@ -178,6 +179,13 @@ export const pluginJsonLinter = {
                 }
             }
         }
+        // gitea#9: mcpServers belongs in `.mcp.json` at the plugin root, not as
+        // a top-level key in `.claude-plugin/plugin.json`. The legacy shape still
+        // loads but uses a different code path and contradicts the official docs.
+        if ("mcpServers" in parsed) {
+            const p = pos("mcpServers");
+            push(diag(config, filePath, "plugin-json/no-inline-mcp-servers", "warning", "\"mcpServers\" should not live inside plugin.json — move to .mcp.json at the plugin root. See https://code.claude.com/docs/en/plugins#plugin-structure-overview", p?.line, p?.column));
+        }
         // license
         if ("license" in parsed && typeof parsed.license === "string") {
             if (!SPDX_COMMON.has(parsed.license)) {