claudecode-linter 2.1.143 → 2.1.148

package/contracts/skill-frontmatter.schema.json

@@ -0,0 +1,182 @@
+{
+	"extractedFromClaudeCodeVersion": "2.1.146",
+	"extractedAt": "2026-05-21T21:04:24.797Z",
+	"schema": {
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		"title": "Claude Code SKILL.md frontmatter",
+		"type": "object",
+		"properties": {
+			"name": {
+				"description": "Display name. Defaults to the filename without extension."
+			},
+			"description": {
+				"description": "One-line summary shown in listings and the Skill tool."
+			},
+			"model": {
+				"description": "Model override (`haiku`, `sonnet`, `opus`, or a full ID). Use `inherit` to match the parent conversation."
+			},
+			"allowed-tools": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Tools available to the model while this file is active. Comma-separated string or YAML list."
+			},
+			"argument-hint": {
+				"description": "Placeholder text shown after the slash command name."
+			},
+			"arguments": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "@internal — typed variant of argument-hint; argument-hint is the documented form"
+			},
+			"disable-model-invocation": {
+				"description": "If true, the model cannot invoke this via the Skill tool; only users can type the slash command."
+			},
+			"user-invocable": {
+				"description": "If false, hides the slash command from users; only the model can invoke it via the Skill tool."
+			},
+			"effort": {
+				"description": "Thinking effort for the model: `low`, `medium`, `high`, `max`, or an integer."
+			},
+			"shell": {
+				"description": "Shell for `!`-command blocks: `bash` or `powershell`. Defaults to bash regardless of platform."
+			},
+			"version": {
+				"description": "@internal — bookkeeping, not surfaced to users"
+			},
+			"when_to_use": {
+				"description": "Guidance for when the model should reach for this skill. Becomes part of the tool description."
+			},
+			"paths": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Glob patterns this skill applies to. The skill only loads when the model touches matching files."
+			},
+			"hooks": {
+				"description": "Hooks registered while this skill is active. Same shape as settings.json `hooks`."
+			},
+			"context": {
+				"enum": [
+					"inline",
+					"fork",
+					null
+				],
+				"description": "Where the skill runs: `inline` expands into the current conversation; `fork` spawns a subagent."
+			},
+			"agent": {
+				"description": "Agent type to spawn when `context: fork`."
+			},
+			"fallback": {
+				"description": "@internal — interim defense-in-depth for thin-pointer skill stubs. If true, this skill yields to a same-suffix plugin or MCP skill (`<plugin>:<name>` / `<server>:<name>`) when one is loaded. Stubs carrying this should be deleted once their canonical plugin/MCP skill ships, not maintained."
+			},
+			"created_by": {
+				"description": "@internal — provenance marker (e.g. dream-proposal)"
+			},
+			"improved_by": {
+				"description": "@internal — provenance marker (e.g. dream-proposal)"
+			},
+			"mcpServers": {
+				"description": "@internal"
+			},
+			"lspServers": {
+				"description": "@internal"
+			},
+			"agents": {
+				"description": "@internal"
+			},
+			"outputStyles": {
+				"description": "@internal"
+			},
+			"themes": {
+				"description": "@internal"
+			},
+			"workflows": {
+				"description": "@internal"
+			},
+			"channels": {
+				"description": "@internal"
+			},
+			"monitors": {
+				"description": "@internal"
+			},
+			"settings": {
+				"description": "@internal"
+			},
+			"experimental": {
+				"description": "@internal"
+			},
+			"dependencies": {
+				"description": "@internal"
+			},
+			"metadata": {
+				"description": "@internal"
+			}
+		},
+		"description": "Claude Code SKILL.md YAML frontmatter. Validates the structure of known fields; the object is intentionally permissive — unknown frontmatter keys are not schema errors (Claude Code still loads the skill), they are reported by the advisory skill-md/no-unknown-frontmatter rule."
+	}
+}

package/dist/contracts.js

@@ -1,11 +1,14 @@
 // Auto-generated from contracts/claude-code-contracts.json
-// Claude Code v2.1.143 — extracted 2026-05-16T00:58:12.730Z
+// Claude Code v2.1.148 — extracted 2026-05-22T07:13:45.210Z
 // Do not edit manually. Run: npm run generate-contracts
 export const TOOLS = new Set([
     "Agent",
     "AskUserQuestion",
     "Bash",
     "Config",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
     "Edit",
     "EnterPlanMode",
     "EnterWorktree",
@@ -16,10 +19,13 @@ export const TOOLS = new Set([
     "LSP",
     "ListMcpResources",
     "Mcp",
+    "Monitor",
     "NotebookEdit",
     "NotebookRead",
+    "PushNotification",
     "Read",
     "ReadMcpResource",
+    "RemoteTrigger",
     "SendMessage",
     "Skill",
     "SubscribeMcpResource",
@@ -164,6 +170,7 @@ export const MCP_SERVER_FIELDS = new Set([
     "headersHelper",
     "oauth",
     "role",
+    "timeout",
     "type",
     "url",
 ]);
@@ -316,7 +323,63 @@ export const SETTINGS_USER_FIELDS = new Set([
     "wslInheritsWindowsSettings",
 ]);
 export const SETTINGS_PROJECT_FIELDS = new Set([
+    "hooks",
     "permissions",
+    "sandbox",
+]);
+// Allowed sub-keys of the settings `permissions` object.
+export const PERMISSIONS_FIELDS = new Set([
+    "additionalDirectories",
+    "allow",
+    "ask",
+    "defaultMode",
+    "deny",
+    "disableAutoMode",
+    "disableBypassPermissionsMode",
+]);
+// Allowed sub-keys of the settings `sandbox` object.
+export const SANDBOX_FIELDS = new Set([
+    "allowUnsandboxedCommands",
+    "autoAllowBashIfSandboxed",
+    "bwrapPath",
+    "enableWeakerNestedSandbox",
+    "enableWeakerNetworkIsolation",
+    "enabled",
+    "excludedCommands",
+    "failIfUnavailable",
+    "filesystem",
+    "ignoreViolations",
+    "network",
+    "ripgrep",
+]);
+// Allowed sub-keys of `sandbox.network` and `sandbox.filesystem`.
+export const SANDBOX_NETWORK_FIELDS = new Set([
+    "allowAllUnixSockets",
+    "allowLocalBinding",
+    "allowMachLookup",
+    "allowManagedDomainsOnly",
+    "allowUnixSockets",
+    "allowedDomains",
+    "deniedDomains",
+    "httpProxyPort",
+    "socksProxyPort",
+    "tlsTerminate",
+]);
+export const SANDBOX_FILESYSTEM_FIELDS = new Set([
+    "allowManagedReadPathsOnly",
+    "allowRead",
+    "allowWrite",
+    "denyRead",
+    "denyWrite",
+]);
+// Valid values for `permissions.defaultMode`.
+export const PERMISSION_MODES = new Set([
+    "acceptEdits",
+    "auto",
+    "bypassPermissions",
+    "default",
+    "dontAsk",
+    "plan",
 ]);
 // Hand-curated denylist of tools declared in agent frontmatter that never
 // reach plugin-defined subagents at runtime. Source: tracked upstream bugs

package/dist/discovery.js

@@ -79,6 +79,25 @@ export function discoverArtifacts(targetPath, options) {
     }
     return artifacts;
 }
+/**
+ * Detect which Claude Code artifact types are present under the given paths.
+ * Returns the distinct types, sorted; excludes the `misplaced-file` diagnostic
+ * category (it marks a misplacement, not a kind of artifact a project owns).
+ * An empty result means the path holds no recognizable Claude Code artifacts.
+ *
+ * Powers the `--detect` CLI mode: a generic git hook can call it to decide
+ * whether a repository is a Claude Code plugin / config tree before linting.
+ */
+export function detectArtifactTypes(paths, ignore = []) {
+    const found = new Set();
+    for (const targetPath of paths) {
+        for (const a of discoverArtifacts(targetPath, { ignore })) {
+            if (a.artifactType !== "misplaced-file")
+                found.add(a.artifactType);
+        }
+    }
+    return [...found].sort();
+}
 function detectScope(filePath) {
     const resolved = resolve(filePath);
     // Inside ~/.claude/ itself (not a subdirectory project)
@@ -253,8 +272,9 @@ function discoverInDirectory(dir) {
  * sitting at a non-canonical location is returned as a
  * `misplaced-file` artifact for the misplaced-file linter to flag.
  *
- * Ignores typical noise dirs (`node_modules`, `.git`, `dist`, the
- * plugin install cache's `.in_use` / `.orphaned_at` markers).
+ * Ignores typical noise dirs (`node_modules`, `.git`, `dist`,
+ * `.claude/worktrees/` worktree copies, the plugin install cache's
+ * `.in_use` / `.orphaned_at` markers).
  */
 function findMisplacedFiles(pluginRoot) {
     const out = [];
@@ -270,6 +290,10 @@ function findMisplacedFiles(pluginRoot) {
             ignore: [
                 "**/node_modules/**",
                 "**/.git/**",
+                // `.claude/worktrees/` holds transient git-worktree copies
+                // (Claude Code's own EnterWorktree). Linting them re-reports
+                // every artifact once per worktree — pure noise.
+                "**/.claude/worktrees/**",
                 "**/dist/**",
                 "**/.in_use/**",
                 "**/.orphaned_at/**",

package/dist/fixers/settings-json.js

@@ -1,6 +1,8 @@
 import { formatJson } from "../utils/prettier.js";
 const TOP_LEVEL_KEY_ORDER = [
     "permissions",
+    "sandbox",
+    "hooks",
     "env",
     "plugins",
     "skipDangerousModePermissionPrompt",
@@ -30,15 +32,14 @@ export const settingsJsonFixer = {
                 ordered[key] = parsed[key];
             }
         }
-        // Sort permissions.allow and permissions.deny alphabetically
+        // Sort the permissions.allow / deny / ask rule arrays alphabetically
         const permissions = ordered["permissions"];
         if (typeof permissions === "object" && permissions !== null && !Array.isArray(permissions)) {
             const perms = permissions;
-            if (Array.isArray(perms["allow"])) {
-                perms["allow"] = [...perms["allow"]].sort();
-            }
-            if (Array.isArray(perms["deny"])) {
-                perms["deny"] = [...perms["deny"]].sort();
+            for (const list of ["allow", "deny", "ask"]) {
+                if (Array.isArray(perms[list])) {
+                    perms[list] = [...perms[list]].sort();
+                }
             }
         }
         return formatJson(JSON.stringify(ordered));

package/dist/index.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import sade from "sade";
 import pc from "picocolors";
 import { loadConfig, mergeCliRules } from "./config.js";
-import { discoverArtifacts } from "./discovery.js";
+import { discoverArtifacts, detectArtifactTypes } from "./discovery.js";
 import { formatHuman } from "./formatters/human.js";
 import { formatJson } from "./formatters/json.js";
 import { pluginJsonLinter } from "./linters/plugin-json.js";
@@ -110,19 +110,20 @@ const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.met
 sade("claudecode-linter", true)
     .version(pkgVersion)
     .describe("Linter for Claude Code plugin artifacts")
-    .option("--lint", "Lint artifacts and report issues (default)")
-    .option("--fix", "Auto-fix lint violations, then report remaining issues")
-    .option("--format", "Format all artifacts for consistent style (no lint output)")
+    .option("--lint", "Lint artifacts and report issues (default)", false)
+    .option("--fix", "Auto-fix lint violations, then report remaining issues", false)
+    .option("--format", "Format all artifacts for consistent style (no lint output)", false)
     .option("--output", "Output format: human | json", "human")
     .option("--config", "Config file path")
     .option("--scope", "Filter by scope: user | project | subdirectory")
     .option("--ignore", "Comma-separated glob patterns to ignore")
-    .option("--quiet", "Only show errors")
+    .option("--quiet", "Only show errors", false)
     .option("--enable", "Comma-separated rule IDs to enable")
     .option("--disable", "Comma-separated rule IDs to disable")
     .option("--rule", "Run only this single rule ID")
-    .option("--list-rules", "Print all rules with their default severity and exit")
-    .option("--fix-dry-run", "Run fixers but print diff instead of writing")
+    .option("--list-rules", "Print all rules with their default severity and exit", false)
+    .option("--detect", "Print detected Claude Code artifact type(s), one per line; exit 0 if any, 1 if none", false)
+    .option("--fix-dry-run", "Run fixers but print diff instead of writing", false)
     .option("--init", "Copy default config to path (default: current directory)")
     .action(async (opts) => {
     // sade accepts variadic positional via opts._; default to ["."] when empty.
@@ -153,6 +154,21 @@ sade("claudecode-linter", true)
             }
             process.exit(0);
         }
+        if (opts.detect) {
+            const ignoreD = opts.ignore
+                ?.split(",")
+                .map((p) => p.trim())
+                .filter(Boolean) ?? [];
+            const types = detectArtifactTypes(paths, ignoreD);
+            if (opts.output === "json") {
+                process.stdout.write(`${JSON.stringify(types)}\n`);
+            }
+            else {
+                for (const t of types)
+                    process.stdout.write(`${t}\n`);
+            }
+            process.exit(types.length > 0 ? 0 : 1);
+        }
         const enableList = opts.enable
             ? opts.enable
                 .split(",")

package/dist/linters/agent-md.js

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { AGENT_FRONTMATTER, AGENT_MODELS, AGENT_COLORS, TOOLS, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { AGENT_MODELS, AGENT_COLORS, TOOLS, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { formatAjvError, loadAgentFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
+import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 function findPluginRoot(agentFilePath) {
     let dir = dirname(agentFilePath);
     for (let i = 0; i < 10; i++) {
@@ -56,10 +58,11 @@ function parseToolsField(v) {
 }
 const RULES = [
     { id: "agent-md/valid-frontmatter", defaultSeverity: "error" },
+    { id: "agent-md/schema-valid", defaultSeverity: "error" },
     { id: "agent-md/name-required", defaultSeverity: "error" },
     { id: "agent-md/name-format", defaultSeverity: "error" },
     { id: "agent-md/description-required", defaultSeverity: "error" },
-    { id: "agent-md/description-examples", defaultSeverity: "warning" },
+    { id: "agent-md/description-routing-guidance", defaultSeverity: "warning" },
     { id: "agent-md/model-required", defaultSeverity: "error" },
     { id: "agent-md/model-valid", defaultSeverity: "warning" },
     { id: "agent-md/color-required", defaultSeverity: "warning" },
@@ -97,6 +100,26 @@ export const agentMdLinter = {
             push(diag(config, filePath, "agent-md/valid-frontmatter", "error", fm.error ?? "Invalid frontmatter"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's agent frontmatter Zod validator.
+        // The hand-written rules below add Claude-Code-specific advice with
+        // friendlier messages (model-valid / color-valid re-check fields the
+        // schema also covers — that minimal double-reporting is acceptable).
+        // The extracted schema is intentionally permissive about unknown
+        // frontmatter keys (Claude Code still loads the agent), so those are
+        // NOT reported here — agent-md/no-unknown-frontmatter handles them.
+        // Skipped silently if the schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "agent-md/schema-valid")) {
+            const compiled = loadAgentFrontmatterSchema();
+            if (compiled) {
+                const ok = compiled.validate(fm.data);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        push(diag(config, filePath, "agent-md/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
         // name
         if (!("name" in fm.data) || typeof fm.data.name !== "string") {
             push(diag(config, filePath, "agent-md/name-required", "error", '"name" is required in frontmatter'));
@@ -115,8 +138,16 @@ export const agentMdLinter = {
             push(diag(config, filePath, "agent-md/description-required", "error", '"description" is required in frontmatter'));
         }
         else {
-            if (!/<example>/i.test(fm.data.description)) {
-                push(diag(config, filePath, "agent-md/description-examples", "warning", "Description should include <example> blocks for triggering"));
+            // An agent description must convey *when to route to it*. Three
+            // forms satisfy that: <example> blocks (the upstream few-shot
+            // convention), an explicit routing-triggers block, or prose that
+            // states the triggers. Warn only when the description does none.
+            const desc = fm.data.description;
+            const hasExamples = /<example>/i.test(desc);
+            const hasRoutingTriggers = /ROUTING TRIGGERS/i.test(desc);
+            const hasTriggerProse = /\b(use (it |this )?(for|when|to)\b|use this (agent|skill)|trigger(s|ed)? (on|by|when)|when the user|for any (task|request|work)|invoke (this|when))/i.test(desc);
+            if (!hasExamples && !hasRoutingTriggers && !hasTriggerProse) {
+                push(diag(config, filePath, "agent-md/description-routing-guidance", "warning", "Description should convey when to route to this agent — via <example> blocks, a routing-triggers block (<!-- BEGIN ROUTING TRIGGERS -->…<!-- END ROUTING TRIGGERS -->), or prose stating the triggers"));
             }
         }
         // model
@@ -134,11 +165,15 @@ export const agentMdLinter = {
         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}")`));
         }
-        // unknown frontmatter fields
-        const knownFields = new Set([...AGENT_FRONTMATTER, "name", "color"]);
+        // Frontmatter keys: only flag cross-artifact misplacement. A key valid
+        // for a *different* markdown artifact (e.g. a skill-only key on an
+        // agent) gets an info; a key valid for no artifact stays silent.
+        // "name"/"color" are agent-valid but absent from the contract set.
+        const extraKnown = new Set(["name", "color"]);
         for (const key of Object.keys(fm.data)) {
-            if (!knownFields.has(key)) {
-                push(diag(config, filePath, "agent-md/no-unknown-frontmatter", "info", `Unknown frontmatter field "${key}"`));
+            const cls = classifyUnknownFrontmatterKey(key, "agent", extraKnown);
+            if (cls?.kind === "owned-by-other" && cls.owner) {
+                push(diag(config, filePath, "agent-md/no-unknown-frontmatter", "info", `"${key}" is ${artifactLabel(cls.owner)} frontmatter — Claude Code ignores it on an agent`));
             }
         }
         // system prompt (body)

package/dist/linters/claude-md.js

@@ -50,10 +50,22 @@ export const claudeMdLinter = {
             push(diag(config, filePath, "claude-md/user-level-concise", "info", `User-level CLAUDE.md is ${lines.length} lines — keep global rules concise, put project-specific content in project CLAUDE.md files`));
         }
         if (scope === "project") {
-            // Project CLAUDE.md should have a project description
-            const hasProjectOverview = lines.some((l) => /^#+ .*(overview|project|about|description|what this is|introduction|summary)/i.test(l));
+            // Project CLAUDE.md should describe the project. This is satisfied by
+            // either an explicit overview-style heading OR descriptive prose near
+            // the top — a CLAUDE.md that opens with a title followed by a sentence
+            // of project description does not need a literal "Overview" heading.
+            const hasOverviewHeading = lines.some((l) => /^#+ .*(overview|project|about|description|what this is|introduction|summary)/i.test(l));
+            // Descriptive opening prose: a non-heading, non-list, non-blank line
+            // of reasonable length appearing before the first H2 section.
+            const firstH2 = lines.findIndex((l) => /^## /.test(l));
+            const preambleEnd = firstH2 >= 0 ? firstH2 : lines.length;
+            const hasOpeningProse = lines.slice(0, preambleEnd).some((l) => {
+                const t = l.trim();
+                return t.length >= 25 && !t.startsWith("#") && !/^[-*>|]/.test(t);
+            });
+            const hasProjectOverview = hasOverviewHeading || hasOpeningProse;
             if (!hasProjectOverview && h2Count > 0) {
-                push(diag(config, filePath, "claude-md/project-has-overview", "info", "Project CLAUDE.md should include a project overview section"));
+                push(diag(config, filePath, "claude-md/project-has-overview", "info", "Project CLAUDE.md should include a project overview — an \"Overview\" section or descriptive opening prose"));
             }
         }
         // detect potential secrets

package/dist/linters/command-md.js

@@ -1,8 +1,11 @@
-import { COMMAND_FRONTMATTER, TOOLS } from "../contracts.js";
+import { TOOLS } from "../contracts.js";
+import { formatAjvError, loadCommandFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
+import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 const RULES = [
     { id: "command-md/valid-frontmatter", defaultSeverity: "error" },
+    { id: "command-md/schema-valid", defaultSeverity: "error" },
     { id: "command-md/description-required", defaultSeverity: "error" },
     { id: "command-md/allowed-tools-valid", defaultSeverity: "warning" },
     { id: "command-md/body-present", defaultSeverity: "warning" },
@@ -31,6 +34,25 @@ export const commandMdLinter = {
             push(diag(config, filePath, "command-md/valid-frontmatter", "error", fm.error ?? "Invalid frontmatter"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's command frontmatter Zod validator.
+        // The hand-written rules below add Claude-Code-specific advice (known
+        // tool names, body presence). The extracted schema is intentionally
+        // permissive about unknown frontmatter keys (Claude Code still loads the
+        // command), so those are NOT reported here — command-md/no-unknown-
+        // frontmatter handles them. Skipped silently if the schema bundle isn't
+        // shipped with this install.
+        if (isRuleEnabled(config, "command-md/schema-valid")) {
+            const compiled = loadCommandFrontmatterSchema();
+            if (compiled) {
+                const ok = compiled.validate(fm.data);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        push(diag(config, filePath, "command-md/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
         // description
         if (!("description" in fm.data) || typeof fm.data.description !== "string") {
             push(diag(config, filePath, "command-md/description-required", "error", "\"description\" is required in frontmatter"));
@@ -46,11 +68,15 @@ export const commandMdLinter = {
                 }
             }
         }
-        // unknown frontmatter fields
-        const knownFields = new Set([...COMMAND_FRONTMATTER, "allowed-tools", "argument-hint"]);
+        // Frontmatter keys: only flag cross-artifact misplacement. A key valid
+        // for a *different* markdown artifact gets an info; a key valid for no
+        // artifact stays silent. The hyphenated "allowed-tools"/"argument-hint"
+        // are command-valid aliases of the camelCase contract keys.
+        const extraKnown = new Set(["allowed-tools", "argument-hint"]);
         for (const key of Object.keys(fm.data)) {
-            if (!knownFields.has(key)) {
-                push(diag(config, filePath, "command-md/no-unknown-frontmatter", "info", `Unknown frontmatter field "${key}"`));
+            const cls = classifyUnknownFrontmatterKey(key, "command", extraKnown);
+            if (cls?.kind === "owned-by-other" && cls.owner) {
+                push(diag(config, filePath, "command-md/no-unknown-frontmatter", "info", `"${key}" is ${artifactLabel(cls.owner)} frontmatter — Claude Code ignores it on a command`));
             }
         }
         // body

package/dist/linters/mcp-json.js

@@ -2,6 +2,10 @@ import { basename } from "node:path";
 import { MCP_SERVER_FIELDS } from "../contracts.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { isKebabCase } from "../utils/kebab-case.js";
+// Valid `type` values for a URL-based HTTP MCP server. Claude Code v2.1.146
+// accepts both — its HTTP transport schema is
+// `enum(["http","streamable-http"]).transform(()=>"http")`.
+const HTTP_TRANSPORT_TYPES = new Set(["http", "streamable-http"]);
 const RULES = [
     { id: "mcp-json/scope-file-name", defaultSeverity: "warning" },
     { id: "mcp-json/valid-json", defaultSeverity: "error" },
@@ -109,8 +113,11 @@ export const mcpJsonLinter = {
                 catch {
                     push(diag(config, filePath, "mcp-json/url-valid", "error", `Server "${name}" has invalid URL: "${url}"`, sp?.line, sp?.column));
                 }
-                if ("type" in server && server.type !== "http") {
-                    push(diag(config, filePath, "mcp-json/type-matches-transport", "warning", `Server "${name}" has URL but type is "${server.type}" (expected "http")`, sp?.line, sp?.column));
+                // A URL-based HTTP server may declare "http" or "streamable-http".
+                // Claude Code v2.1.146 treats them identically — its HTTP transport
+                // schema is `enum(["http","streamable-http"]).transform(()=>"http")`.
+                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));
                 }
             }
             // stdio server checks