{"record":{"id":"5d9779d464cba923","repo":"block/buzz","slug":"plugin-json-unknown-key-key","errorCode":null,"errorMessage":"plugin.json unknown key \"{key}\"","messagePattern":"plugin\\.json unknown key \"(.+?)\"","errorType":"validation","errorClass":"ValidationDiagnostic::Warning","httpStatus":null,"severity":"warning","filePath":"crates/buzz-persona/src/validate.rs","lineNumber":321,"sourceCode":"    let manifest_path = pack_dir.join(\".plugin\").join(\"plugin.json\");\n    let content = match std::fs::read_to_string(&manifest_path) {\n        Ok(c) => c,\n        Err(_) => return, // load_pack already caught this\n    };\n    let json: serde_json::Value = match serde_json::from_str(&content) {\n        Ok(v) => v,\n        Err(_) => return, // load_pack already caught this\n    };\n    let obj = match json.as_object() {\n        Some(o) => o,\n        None => return,\n    };\n\n    // Top-level unknown keys.\n    let known_manifest: HashSet<&str> = KNOWN_MANIFEST_KEYS.iter().copied().collect();\n    for key in obj.keys() {\n        if !known_manifest.contains(key.as_str()) {\n            report.warn(format!(\"plugin.json unknown key \\\"{key}\\\"\"));\n        }\n    }\n\n    // Unknown keys in `defaults`.\n    if let Some(defaults) = obj.get(\"defaults\").and_then(|v| v.as_object()) {\n        let known_behavioral: HashSet<&str> = KNOWN_BEHAVIORAL_KEYS.iter().copied().collect();\n        for key in defaults.keys() {\n            if !known_behavioral.contains(key.as_str()) {\n                report.warn(format!(\"plugin.json defaults: unknown key \\\"{key}\\\"\"));\n            }\n        }\n\n        // Unknown keys in `defaults.triggers` (or legacy `defaults.respond_to`).\n        let triggers_obj = defaults\n            .get(\"triggers\")\n            .or_else(|| defaults.get(\"respond_to\"))\n            .and_then(|v| v.as_object());\n        if let Some(rt) = triggers_obj {","sourceCodeStart":303,"sourceCodeEnd":339,"githubUrl":"https://github.com/block/buzz/blob/934f3325c3fdaa3a6f23134b74518139aac8ca3f/crates/buzz-persona/src/validate.rs#L303-L339","documentation":"Advisory lint during persona pack validation: plugin.json carries a top-level key not listed in KNOWN_MANIFEST_KEYS ($schema, id, name, version, description, author, license, homepage, repository, keywords, engines, personas, defaults, pack_instructions, hooks_config, mcp_config). It is emitted as a warning on the ValidationReport and does not abort loading the pack.","triggerScenarios":"A hand-edited plugin.json with a typo'd or speculative top-level key; manifests written by external tooling that injects its own metadata fields; keys from a newer persona-pack spec than this buzz-persona build recognizes.","commonSituations":"Authoring packs against newer or older docs; copy-pasting manifests between plugin ecosystems (e.g. Claude-style plugin.json) into a Buzz persona pack; IDE auto-completing plausible-but-unsupported fields.","solutions":["Compare the offending key against KNOWN_MANIFEST_KEYS in crates/buzz-persona/src/validate.rs:99 and remove or rename it","Upgrade buzz-persona if the key is legitimately part of a newer manifest spec","Validate packs in CI with the same validator so unknown keys surface before publishing"],"exampleFix":"// before (plugin.json)\n{ \"name\": \"helper\", \"display_name\": \"Helper\" }\n\n// after\n{ \"name\": \"helper\", \"description\": \"Helper persona\" }","handlingStrategy":"validation","validationCode":"const KNOWN_MANIFEST_KEYS = new Set([\n  \"$schema\", \"id\", \"name\", \"version\", \"description\", \"author\", \"license\",\n  \"homepage\", \"repository\", \"keywords\", \"engines\", \"personas\", \"defaults\",\n  \"pack_instructions\", \"hooks_config\", \"mcp_config\",\n]); // sync with crates/buzz-persona/src/validate.rs\nfor (const key of Object.keys(manifest)) {\n  if (!KNOWN_MANIFEST_KEYS.has(key)) throw new Error(`plugin.json unknown top-level key: ${key}`);\n}","typeGuard":"const isKnownManifestKey = (k: string): k is ManifestKey => KNOWN_MANIFEST_KEYS.has(k as ManifestKey);","tryCatchPattern":null,"preventionTips":["Validate plugin.json against the KNOWN_MANIFEST_KEYS list in pack CI before publishing","Regenerate manifests from a typed schema rather than editing JSON by hand","Re-run buzz-persona validation after upgrading so newly supported or removed keys surface early"],"tags":["rust","plugin-json","manifest","lint","persona","validation"],"backgroundTag":"unknown-manifest-key","analyzedSha":"934f3325c3fdaa3a6f23134b74518139aac8ca3f","analyzedAt":"2026-08-20T04:38:24.874Z","contentChangedAt":"2026-08-20T04:38:24.874Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}