claudecode-linter 2.1.150 → 2.1.152

package/contracts/settings.schema.json

@@ -1,13 +1,13 @@
 {
-	"extractedFromClaudeCodeVersion": "2.1.146",
-	"extractedAt": "2026-05-22T08:16:43.683Z",
+	"extractedFromClaudeCodeVersion": "2.1.152",
+	"extractedAt": "2026-05-27T07:39:39.197Z",
 	"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,10 @@
 				"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)."
+			},
 			"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 +614,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": [
 					{
@@ -1836,6 +1886,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,7 +2385,7 @@
 			},
 			"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",

package/contracts/skill-frontmatter.schema.json

@@ -1,6 +1,6 @@
 {
-	"extractedFromClaudeCodeVersion": "2.1.146",
-	"extractedAt": "2026-05-22T08:49:59.762Z",
+	"extractedFromClaudeCodeVersion": "2.1.152",
+	"extractedAt": "2026-05-27T07:39:39.199Z",
 	"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.152 — extracted 2026-05-27T07:39:34.438Z
 // 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,6 +250,7 @@ export const SETTINGS_USER_FIELDS = new Set([
     "disableBackgroundAgents",
     "disableRemoteControl",
     "disableSkillShellExecution",
+    "disableWorkflows",
     "disabledMcpjsonServers",
     "doneMeansMerged",
     "editorMode",
@@ -283,6 +285,7 @@ export const SETTINGS_USER_FIELDS = new Set([
     "permissions",
     "plansDirectory",
     "pluginConfigs",
+    "pluginSuggestionMarketplaces",
     "pluginTrustMessage",
     "policyHelper",
     "prUrlTemplate",

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)) {

package/dist/linters/settings-json.js

@@ -1,11 +1,14 @@
-import { basename } from "node:path";
-import { SETTINGS_USER_FIELDS, SETTINGS_PROJECT_FIELDS, TOOLS, PERMISSIONS_FIELDS, PERMISSION_MODES, SANDBOX_FIELDS, SANDBOX_NETWORK_FIELDS, SANDBOX_FILESYSTEM_FIELDS, } from "../contracts.js";
+import { basename, dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { SETTINGS_USER_FIELDS, TOOLS, PERMISSIONS_FIELDS, PERMISSION_MODES, SANDBOX_FIELDS, SANDBOX_NETWORK_FIELDS, SANDBOX_FILESYSTEM_FIELDS, } from "../contracts.js";
 import { formatAjvError, loadSettingsSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 const RULES = [
     { id: "settings-json/valid-json", defaultSeverity: "error" },
     { id: "settings-json/schema-valid", defaultSeverity: "error" },
-    { id: "settings-json/scope-file-name", defaultSeverity: "error" },
+    // settings-json/scope-file-name removed in gitea#4 — .claude/settings.json
+    // is a valid project-shared settings source. See misplaced-file/* for
+    // wrong-path warnings.
     { id: "settings-json/scope-field", defaultSeverity: "warning" },
     { id: "settings-json/no-unknown-fields", defaultSeverity: "warning" },
     { id: "settings-json/permissions-object", defaultSeverity: "error" },
@@ -28,6 +31,7 @@ const RULES = [
     { id: "settings-json/plugins-boolean", defaultSeverity: "warning" },
     { id: "settings-json/plugins-format", defaultSeverity: "warning" },
     { id: "settings-json/skip-prompt-boolean", defaultSeverity: "error" },
+    { id: "settings-json/disable-project-mcpjson-shadow", defaultSeverity: "warning" },
 ];
 // Expected type for each known sandbox sub-key, and for the nested
 // network/filesystem objects. Mirrors Claude Code's Zod schema.
@@ -242,22 +246,47 @@ export const settingsJsonLinter = {
                 }
             }
         }
-        // Scope-aware: settings.json (non-local) should only be at user level
-        if (!isLocal && scope && scope !== "user") {
-            push(diag(config, filePath, "settings-json/scope-file-name", "error", `"settings.json" should only exist at user level (~/.claude/). Use "settings.local.json" for project-level settings`));
-        }
-        // Determine which fields are valid for this scope
-        const knownFields = (scope === "user" || !scope) ? SETTINGS_USER_FIELDS : SETTINGS_PROJECT_FIELDS;
-        // unknown/misplaced top-level fields
+        // gitea#4: `.claude/settings.json` is a first-class project settings source
+        // (`projectSettings`, committed/shared) distinct from `.claude/settings.local.json`
+        // (`localSettings`, gitignored). Claude Code's bundle defines both:
+        //   `case "projectSettings": return Rk.join(".claude","settings.json")`
+        //   `case "localSettings":   return "project, gitignored"`
+        // The rule no longer fires for plain project-level settings.json; the
+        // `misplaced-file/canonical-location` rule covers files at the wrong path.
+        // Determine which fields are valid for this scope. gitea#2: the legacy
+        // SETTINGS_PROJECT_FIELDS whitelist is too narrow — Claude Code accepts
+        // most user-level fields at project scope too. We now treat all known
+        // user fields as valid at project scope, except a small denylist of
+        // genuinely user-only fields (auth helpers, plugin enablement, dangerous
+        // mode), which still warn via `settings-json/scope-field`.
+        const knownFields = SETTINGS_USER_FIELDS;
+        // Fields that genuinely only take effect at user scope. Project-scope
+        // versions are silently ignored by Claude Code. Source: bundle inspection
+        // (auth helpers run from user creds; enabledPlugins / skip-permission
+        // flags can't be enabled by a checked-in repo for security reasons).
+        const USER_ONLY_FIELDS = new Set([
+            "apiKeyHelper",
+            "awsAuthRefresh",
+            "awsCredentialExport",
+            "gcpAuthRefresh",
+            "proxyAuthHelper",
+            "policyHelper",
+            "enabledPlugins",
+            "skipDangerousModePermissionPrompt",
+            "forceLoginMethod",
+            "forceLoginOrgUUID",
+        ]);
+        // unknown / misplaced top-level fields
         for (const key of Object.keys(parsed)) {
             if (!knownFields.has(key)) {
                 const p = findKeyPosition(content, key);
-                if (SETTINGS_USER_FIELDS.has(key) && scope && scope !== "user") {
-                    push(diag(config, filePath, "settings-json/scope-field", "warning", `"${key}" is a user-level field — it has no effect in project-level settings.local.json`, p?.line, p?.column));
-                }
-                else if (!SETTINGS_USER_FIELDS.has(key)) {
-                    push(diag(config, filePath, "settings-json/no-unknown-fields", "warning", `Unknown top-level field "${key}"`, p?.line, p?.column));
-                }
+                push(diag(config, filePath, "settings-json/no-unknown-fields", "warning", `Unknown top-level field "${key}"`, p?.line, p?.column));
+                continue;
+            }
+            // gitea#2: only the genuinely user-only denylist warns at project scope.
+            if (USER_ONLY_FIELDS.has(key) && scope && scope !== "user") {
+                const p = findKeyPosition(content, key);
+                push(diag(config, filePath, "settings-json/scope-field", "warning", `"${key}" only takes effect at user level (~/.claude/settings.json); it is ignored in project settings`, p?.line, p?.column));
             }
         }
         // Validate the sub-keys of a nested object against a known-field set and a
@@ -444,6 +473,50 @@ export const settingsJsonLinter = {
                 }
             }
         }
+        // gitea#8: when this settings.json sits at <plugin-root>/.claude/settings.json
+        // and the plugin also ships a <plugin-root>/.mcp.json, Claude Code loads the
+        // plugin's MCP servers twice when launched from the plugin dir (once as the
+        // plugin, once as project-scope .mcp.json) and dedupes — triggering /doctor
+        // "skipped" warnings. The committed suppression is to list each server name
+        // in this file's `disabledMcpjsonServers`.
+        if (isRuleEnabled(config, "settings-json/disable-project-mcpjson-shadow") &&
+            basename(filePath) === "settings.json" &&
+            basename(dirname(filePath)) === ".claude") {
+            const pluginRoot = dirname(dirname(filePath));
+            const pluginJson = join(pluginRoot, ".claude-plugin", "plugin.json");
+            const mcpJson = join(pluginRoot, ".mcp.json");
+            if (existsSync(pluginJson) && existsSync(mcpJson)) {
+                let mcpServerNames = [];
+                try {
+                    const mcp = JSON.parse(readFileSync(mcpJson, "utf-8"));
+                    if (isPlainObject(mcp.mcpServers)) {
+                        mcpServerNames = Object.keys(mcp.mcpServers);
+                    }
+                }
+                catch { /* ignore — broken .mcp.json is the mcp-json linter's job */ }
+                // settings.local.json with the same disable also satisfies the rule.
+                let disabled = Array.isArray(parsed.disabledMcpjsonServers)
+                    ? parsed.disabledMcpjsonServers
+                    : [];
+                const localPath = join(dirname(filePath), "settings.local.json");
+                if (existsSync(localPath)) {
+                    try {
+                        const local = JSON.parse(readFileSync(localPath, "utf-8"));
+                        if (Array.isArray(local.disabledMcpjsonServers)) {
+                            disabled = disabled.concat(local.disabledMcpjsonServers);
+                        }
+                    }
+                    catch { /* ignore */ }
+                }
+                const disabledSet = new Set(disabled.filter((x) => typeof x === "string"));
+                const dp = findKeyPosition(content, "disabledMcpjsonServers");
+                for (const name of mcpServerNames) {
+                    if (!disabledSet.has(name)) {
+                        push(diag(config, filePath, "settings-json/disable-project-mcpjson-shadow", "warning", `Server "${name}" is declared in .mcp.json but not in .claude/settings.json#disabledMcpjsonServers — when Claude Code is launched from this plugin directory, the MCP server is loaded twice (plugin + project-level), triggering /doctor "skipped" warnings`, dp?.line, dp?.column));
+                    }
+                }
+            }
+        }
         // skipDangerousModePermissionPrompt — user-level only
         if ("skipDangerousModePermissionPrompt" in parsed) {
             if (typeof parsed.skipDangerousModePermissionPrompt !== "boolean") {

package/dist/linters/skill-md.js

@@ -52,7 +52,13 @@ function hasTriggerSignal(desc) {
     // ("Trigger on …", "Trigger when/whenever/if …", "Triggers: …", "TRIGGER
     // when:") — not when "trigger" merely appears as a noun (e.g. the phrase
     // "no trigger phrases").
-    const triggerPhrases = /\btrigger(s)?\b\s*(on|when|whenever|if|upon|for)\b|\btriggers?\s*:|\buse (this skill |it )?(when|whenever|for|to|on|if)\b|\bshould be used (when|whenever|for|to|if)\b|\b(applies|invoke|reach for|call this|run this|use this) (when|whenever|if|to|for)\b|\bwhen (the user|you|asked|working|debugging|diagnosing|investigating|reviewing|writing|building|creating|editing|setting up|deploying|the task|a request|a question|you need|there|something|anything)\b|\bwhen [a-z]+ing\b|\bfor (debugging|diagnosing|tasks|requests|questions|when|any)\b/i;
+    // gitea#5: widened to accept more applicability phrasings observed in the
+    // wild — "Loaded automatically when …", "when a turn touches …",
+    // "applies to …", "for memory operations", "Memory protocol for the X
+    // MCP" (a noun-opener that names the domain). The runtime makes
+    // `description` optional, so this rule is advisory; aim for low false
+    // positive rate rather than complete coverage.
+    const triggerPhrases = /\btrigger(s)?\b\s*(on|when|whenever|if|upon|for)\b|\btriggers?\s*:|\buse (this skill |it )?(when|whenever|for|to|on|if)\b|\bshould be used (when|whenever|for|to|if)\b|\b(applies|invoke|reach for|call this|run this|use this|loaded|loads|reaches for|fires) (when|whenever|if|to|for|automatically|on)\b|\bwhen (the user|you|asked|working|debugging|diagnosing|investigating|reviewing|writing|building|creating|editing|setting up|deploying|the task|a request|a question|a message|a turn|the turn|the session|the conversation|the model|you need|there|something|anything)\b|\bwhen [a-z]+ing\b|\bfor (debugging|diagnosing|tasks|requests|questions|when|any|memory|recall|search|saves?|the )\b|\bprotocol for\b|\barchivist for\b|\bhandler for\b|\bauto(matic|-?)\s+(save|load|invocation)\b/i;
     if (triggerPhrases.test(d))
         return true;
     // First "sentence-ish" chunk — used to detect imperative / gerund openers.