# ===========================================================================
# Rules - Validator diagnostic messages, suggestions, assumptions, fixes
# ===========================================================================
rules:
  # --- Agent Skills (skill/mod.rs) ---
  as_001:
    message: "SKILL.md must have YAML frontmatter between --- markers"
    suggestion: "Add frontmatter between --- markers"
  as_002:
    message: "Skill frontmatter is missing required 'name' field"
    suggestion: "Add 'name: your-skill-name' to frontmatter"
  as_003:
    message: "Skill frontmatter is missing required 'description' field"
    suggestion: "Add 'description: Use when...' to frontmatter"
  as_004:
    message: "Name '%{name}' must be 1-64 characters of lowercase letters, digits, and hyphens"
    suggestion: "Lowercase and trim the name, replace spaces and '_' with '-', collapse multiple '-' into one, remove invalid characters, and truncate to 64 characters"
    fix: "Convert name to kebab-case: '%{name}'"
  as_005:
    message: "Name '%{name}' cannot start or end with hyphen"
    suggestion: "Remove leading/trailing hyphens from the name"
  as_006:
    message: "Name '%{name}' cannot contain consecutive hyphens"
    suggestion: "Replace '--' with '-' in the name"
  as_008:
    message: "Description must be 1-%{max} characters, got %{len}"
    suggestion: "Trim the description to %{max} characters or fewer"
  as_009:
    message: "Description must not contain XML tags"
    suggestion: "Remove XML tags from the description"
  as_011:
    message: "Compatibility must be 1-500 characters, got %{len}"
    suggestion: "Trim compatibility to 500 characters or fewer"
  as_012:
    message: "Skill content exceeds 500 lines (got %{count})"
    suggestion: "Move extra content into references/"
  as_013:
    message: "File reference '%{path}' is deeper than one level"
    suggestion: "Flatten the references/ directory structure"
  as_015:
    message: "Skill directory exceeds 8MB (%{size} bytes)"
    suggestion: "Remove large assets or split the skill into smaller parts"
  as_016:
    message: "Failed to parse SKILL.md: %{error}"
    suggestion: "Check YAML frontmatter syntax -- ensure proper indentation, colon spacing, and matching quotes"
  as_017:
    message: "Skill name '%{name}' must match parent directory '%{directory}'"
    suggestion: "Rename the skill directory or update the name field so they match"

  # --- Claude Code Skills (skill/mod.rs) ---
  cc_sk_001:
    message: "Invalid model '%{model}'. Must be one of: %{valid}"
    suggestion: "Use one of the valid model values: %{valid}"
  cc_sk_002:
    message: "Invalid context '%{context}'. Must be 'fork' or omitted"
    suggestion: "Set context to 'fork' or remove the field entirely"
  cc_sk_003:
    message: "Context 'fork' requires an 'agent' field"
    suggestion: "Add 'agent: general-purpose' or another valid agent type"
  cc_sk_004:
    message: "Agent field requires 'context: fork'"
    suggestion: "Add 'context: fork' to the frontmatter"
  cc_sk_005:
    message: "Invalid agent type '%{agent}'. Must be Explore, Plan, general-purpose, or a custom kebab-case name (1-64 chars)"
    suggestion: "Use a built-in agent (Explore, Plan, general-purpose) or a custom kebab-case name"
    fix: "Replace invalid agent with 'general-purpose'"
  cc_sk_006:
    message: "Dangerous skill '%{name}' must set 'disable-model-invocation: true' to prevent accidental invocation"
    suggestion: "Add 'disable-model-invocation: true' to the frontmatter"
  cc_sk_007:
    message: "Unrestricted Bash access detected. Consider using scoped version for better security."
    suggestion: "Use scoped Bash like 'Bash(git:*)' or 'Bash(npm:*)' instead of plain 'Bash'"
    fix: "Replace unrestricted Bash with scoped Bash(git:*)"
  cc_sk_008:
    message: "Unknown tool '%{tool}'. Known tools: %{known}. MCP tools must use lowercase mcp__<server>__<tool> format"
    suggestion: "Use one of the known Claude Code tools: %{known}, or a valid MCP tool (mcp__<server>__<tool>, case-sensitive lowercase prefix)"
  cc_sk_009:
    message: "Too many dynamic injections (%{count}). Limit to %{max} for better performance"
    suggestion: "Consider moving complex logic to a scripts/ directory or reducing injections"
  cc_sk_010:
    message: "Invalid hooks configuration in skill frontmatter: %{error}"
    suggestion: "Ensure hooks follow the same schema as settings.json hooks"
  cc_sk_011:
    message: "Skill is unreachable: user-invocable is false and disable-model-invocation is true"
    suggestion: "Set user-invocable to true or disable-model-invocation to false"
    fix: "Remove 'disable-model-invocation: true' to allow model invocation"
  cc_sk_012:
    message: "argument-hint is set but body does not reference $ARGUMENTS"
    suggestion: "Add $ARGUMENTS to the skill body or remove the argument-hint field"
  cc_sk_013:
    message: "context: fork with reference-only content lacks actionable instructions"
    suggestion: "Add imperative instructions for the forked agent to follow"
  cc_sk_014:
    message: "disable-model-invocation must be a boolean, got string '%{value}'"
    suggestion: "Use true/false without quotes"
    fix: "Convert string '%{value}' to boolean %{fixed}"
  cc_sk_015:
    message: "user-invocable must be a boolean, got string '%{value}'"
    suggestion: "Use true/false without quotes"
    fix: "Convert string '%{value}' to boolean %{fixed}"
  cc_sk_016:
    message: "Body uses indexed $ARGUMENTS[n] but argument-hint is missing"
    suggestion: "Add argument-hint to frontmatter so users know how to provide arguments"
  cc_sk_017:
    message: "Unknown frontmatter field '%{field}'"
    suggestion: "Remove unsupported fields or fix typos in frontmatter keys"

  # --- Per-Client Skills (per_client_skill.rs) ---
  cr_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  cl_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  cp_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  cx_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  oc_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  ws_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  kr_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  amp_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  rc_sk_001:
    message: "field '%{field}' is not supported by %{client} -- it will be ignored"
    suggestion: "Remove '%{field}' or move this skill to a client that supports it"
  xp_sk_001:
    message: "skill uses client-specific field '%{field}' which is not part of the universal Agent Skills spec"
    suggestion: "Consider removing '%{field}' for cross-platform portability"

  # --- Hooks (hooks/mod.rs) ---
  cc_hk_001:
    message: "Invalid hook event '%{event}', valid events: %{valid}"
    fix: "Replace '%{old}' with '%{new}'"
  cc_hk_002:
    message: "Prompt/agent hook at %{location} is not supported on '%{event}' events"
    suggestion: "Prompt/agent hooks work on PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, and TaskCompleted. Use 'type': 'command' for other events"
  cc_hk_003:
    message: "Tool event '%{event}' at %{location} has no matcher field; omitting it matches all tools"
    suggestion: "Consider adding a 'matcher' field to target specific tools (e.g., 'Bash', 'Read')"
  cc_hk_004:
    message: "Non-tool event '%{event}' at %{location} must not have a matcher field"
    suggestion: "Remove the 'matcher' field"
  cc_hk_005:
    message: "Hook at %{location} is missing required 'type' field"
    suggestion: "Add 'type': 'command', 'type': 'prompt', or 'type': 'agent'"
  cc_hk_006:
    message: "Command hook at %{location} is missing required 'command' field"
    suggestion: "Add a 'command' field with the command to execute"
  cc_hk_007:
    message: "Prompt/agent hook at %{location} is missing required 'prompt' field"
    suggestion: "Add a 'prompt' field with the prompt text"
  cc_hk_008:
    message: "Script file not found at '%{script}' (resolved to '%{resolved}')"
    suggestion: "Create the script file or correct the path"
  cc_hk_009:
    message: "Potentially dangerous command pattern detected: %{reason}"
    suggestion: "Review the command for safety. Pattern matched: %{pattern}"
  cc_hk_010:
    command_no_timeout: "Command hook at %{location} has no timeout specified"
    command_no_timeout_suggestion: "Add a \"timeout\" field (e.g., 600 for command hooks)"
    command_exceeds: "Command hook at %{location} has timeout %{timeout}s exceeding %{default}s default"
    command_exceeds_suggestion: "Consider timeout <= %{default}s (10-minute default limit)"
    prompt_no_timeout: "Prompt/agent hook at %{location} has no timeout specified"
    prompt_no_timeout_suggestion: "Add a \"timeout\" field (e.g., 30 for prompt/agent hooks)"
    prompt_exceeds: "Prompt/agent hook at %{location} has timeout %{timeout}s exceeding %{default}s default"
    prompt_exceeds_suggestion: "Consider timeout <= %{default}s (30-second default limit)"
    assumption: "Assumes Claude Code default timeout behavior. Pin claude_code version in .agnix.toml [tool_versions] for version-specific validation."
  cc_hk_011:
    message: "Invalid timeout value at %{location}: must be a positive integer"
    suggestion: "Set timeout to a positive integer like 30"
  cc_hk_012:
    message: "Failed to parse hooks configuration: %{error}"
    suggestion: "Validate JSON syntax in hooks configuration -- check for missing commas, brackets, or unquoted keys"
  cc_hk_013:
    message: "async field is only valid on command hooks, not %{hook_type} hooks at %{location}"
    suggestion: "Remove the async field or change the hook type to command"
    fix: "Remove 'async' field (has no effect on non-command hooks)"
  cc_hk_014:
    message: "once field at %{location} is only meaningful in skill/agent frontmatter hooks"
    suggestion: "Remove the once field from settings.json hooks"
  cc_hk_015:
    message: "model field is only valid on prompt/agent hooks, not command hooks at %{location}"
    suggestion: "Remove the model field or change the hook type to prompt/agent"
    fix: "Remove 'model' field (has no effect on command hooks)"
  cc_hk_016:
    message: "Unknown hook type '%{hook_type}' at %{location}"
    suggestion: "Valid hook types are: command, prompt, agent"
    fix: "Change hook type to '%{fixed}'"
  cc_hk_017:
    message: "Prompt/agent hook at %{location} does not reference $ARGUMENTS"
    suggestion: "Include $ARGUMENTS in the prompt to receive event context"
  cc_hk_018:
    message: "Matcher at %{location} is silently ignored for '%{event}' events"
    suggestion: "Remove the matcher field as it has no effect on %{event} events"
    fix: "Remove 'matcher' field (ignored on %{event} events)"

  cc_hk_019:
    message: "Deprecated hook event '%{event}' - use '%{replacement}' instead"
    suggestion: "'%{event}' is not listed in current Claude Code documentation. Use '%{replacement}' for forward compatibility"
    fix: "Replace '%{event}' with '%{replacement}'"
  # --- MCP (mcp.rs) ---
  mcp_001:
    invalid_version: "Invalid JSON-RPC version '%{version}', must be '2.0'"
    not_string: "JSON-RPC version must be a string"
    suggestion: "Set \"jsonrpc\": \"2.0\""
  mcp_002:
    missing_name: "%{prefix}Missing required field 'name'"
    missing_name_suggestion: "Add 'name' field to tool definition"
    missing_description: "%{prefix}Missing required field 'description'"
    missing_description_suggestion: "Add 'description' field to tool definition"
    missing_schema: "%{prefix}Missing required field 'inputSchema'"
    missing_schema_suggestion: "Add 'inputSchema' field with JSON Schema definition"
  mcp_003:
    message: "%{prefix}Invalid inputSchema: %{error}"
    suggestion: "Fix JSON Schema structure -- valid 'type' values are: string, number, integer, boolean, object, array, null"
  mcp_004:
    message: "%{prefix}Tool description is too short (%{len} chars), should be at least 10 characters"
    suggestion: "Add a meaningful description explaining what the tool does"
  mcp_005:
    message: "%{prefix}Tool lacks consent mechanism (no 'requiresApproval' or 'confirmation' field)"
    suggestion: "Consider adding 'requiresApproval: true' for tools that modify data or have side effects"
  mcp_006:
    message: "%{prefix}Tool has annotations that should be validated before trusting"
    suggestion: "Verify annotation values independently -- annotations are self-reported by the server and may be inaccurate or malicious"
  mcp_007:
    message: "Failed to parse MCP configuration: %{error}"
    suggestion: "Validate JSON syntax -- check for missing commas, brackets, or unquoted keys"
  mcp_008:
    message: "Protocol version mismatch: found '%{found}', expected '%{expected}'"
    request_suggestion: "Consider updating to protocol version '%{expected}' for compatibility"
    response_suggestion: "Server negotiated version '%{found}', expected '%{expected}'. Verify compatibility."
    assumption: "Using default MCP protocol version. Pin mcp_protocol in .agnix.toml [spec_revisions] for explicit control."
  mcp_009:
    message: "Server '%{server}' has type 'stdio' but is missing required 'command' field"
    suggestion: "Add a 'command' field specifying the executable to run"
  mcp_010:
    message: "Server '%{server}' has type '%{server_type}' but is missing required 'url' field"
    suggestion: "Add a 'url' field specifying the server endpoint"
  mcp_011:
    message: "Server '%{server}' has invalid type '%{server_type}'. Must be 'stdio', 'http', or 'sse'"
    suggestion: "Use one of: stdio, http, sse"
    fix: "Change server type to '%{fixed}'"
  mcp_012:
    message: "Server '%{server}' uses deprecated SSE transport"
    suggestion: "Consider changing type from 'sse' to 'http' (Streamable HTTP)"
    fix: "Change type from 'sse' to 'http'"
  invalid_tool: "Tool #%{num}: Invalid tool definition: %{error}"
  invalid_tool_single: "Invalid tool definition: %{error}"
  invalid_tool_suggestion: "Ensure tool has valid field types (name: string, description: string, inputSchema: object)"

  # --- Agent (agent.rs) ---
  cc_ag_001:
    message: "Agent frontmatter is missing required 'name' field"
    suggestion: "Add 'name: your-agent-name' to frontmatter"
  cc_ag_002:
    message: "Agent frontmatter is missing required 'description' field"
    suggestion: "Add 'description: Describe what this agent does' to frontmatter"
  cc_ag_003:
    message: "Invalid model '%{model}'. Valid values: %{valid}"
    suggestion: "Change model to one of: %{valid}"
  cc_ag_004:
    message: "Invalid permissionMode '%{mode}'. Valid values: %{valid}"
    suggestion: "Change permissionMode to one of: %{valid}"
  cc_ag_005:
    message: "Referenced skill '%{skill}' not found at .claude/skills/%{skill}/SKILL.md"
    suggestion: "Create the skill at .claude/skills/%{skill}/SKILL.md or remove the reference"
  cc_ag_006:
    message: "Tool(s) appear in both 'tools' and 'disallowedTools': %{conflicts}"
    suggestion: "Remove conflicting tool(s) from either 'tools' or 'disallowedTools'"
  cc_ag_007:
    message: "Agent file must have YAML frontmatter"
    suggestion: "Add frontmatter between --- markers"
    parse_error: "Failed to parse agent frontmatter: %{error}"
    parse_error_suggestion: "Check YAML frontmatter syntax -- ensure proper indentation, colon spacing, and matching quotes"
  cc_ag_008:
    message: "Invalid memory scope '%{scope}'. Must be 'user', 'project', or 'local'"
    suggestion: "Use one of: user, project, local"
    fix: "Change memory scope to '%{fixed}'"
  cc_ag_009:
    message: "Unknown tool '%{tool}' in tools list. Known tools: %{known}. MCP tools must use lowercase mcp__<server>__<tool> format"
    suggestion: "Use a known Claude Code tool name or a valid MCP tool (mcp__<server>__<tool>, case-sensitive lowercase prefix)"
  cc_ag_010:
    message: "Unknown tool '%{tool}' in disallowedTools list. Known tools: %{known}"
    suggestion: "Use a known Claude Code tool name or a valid MCP tool (mcp__<server>__<tool>, case-sensitive lowercase prefix)"
  cc_ag_011:
    message: "Invalid hooks configuration in agent frontmatter: %{error}"
    suggestion: "Ensure hooks follow the same schema as settings.json hooks"
  cc_ag_012:
    message: "permissionMode 'bypassPermissions' disables all safety checks"
    suggestion: "Consider using 'dontAsk' or 'acceptEdits' for a safer permission mode"
    fix: "Replace 'bypassPermissions' with 'default'"
  cc_ag_013:
    message: "Invalid skill name format '%{name}'. Must be lowercase with hyphens"
    suggestion: "Use kebab-case format (e.g., 'my-skill-name')"

  # --- Claude MD (claude_md.rs) ---
  cc_mem_004:
    message: "npm script '%{script}' not found in package.json"
    suggestion_no_scripts: "No scripts defined in package.json."
    suggestion_available: "Available scripts: %{scripts}"
  cc_mem_005:
    message: "Generic instruction '%{text}' - Claude already knows this"
    suggestion: "Remove generic instructions. Focus on project-specific context."
    fix: "Remove generic instruction line"
  cc_mem_006:
    message: "Negative instruction '%{text}' without positive alternative"
    suggestion: "Add a positive alternative: 'Instead, do...' or 'Use X instead.'"
  cc_mem_007:
    message: "Weak constraint '%{text}' in critical section '%{section}'"
    suggestion: "Use strong language in critical sections: 'must', 'always', 'required'."
    fix: "Replace '%{text}' with stronger language"
  cc_mem_008:
    message: "Critical keyword '%{keyword}' at %{percent} percent of document (middle zone)"
    suggestion: "Move critical content to the top or bottom of the document for better recall."
  cc_mem_009:
    message: "File exceeds recommended token limit (~%{tokens} tokens, limit is %{limit})"
    suggestion: "Consider using @import to split content into multiple files."
  cc_mem_010:
    message: "CLAUDE.md has %{overlap} percent overlap with README.md (threshold: %{threshold} percent)"
    suggestion: "CLAUDE.md should complement README, not duplicate it. Remove duplicated sections."

  # --- Claude Rules (.claude/rules/*.md) ---
  cc_mem_011:
    message: "Invalid glob pattern '%{pattern}' in paths field (item %{index}): %{error}"
    suggestion: "Fix the glob pattern syntax. Valid examples: 'src/**/*.ts', '*.rs', 'tests/**/*.test.js'"
  cc_mem_012:
    message: "Unknown frontmatter key '%{key}' in .claude/rules file"
    suggestion: "Only 'paths' is a recognized key in .claude/rules/*.md frontmatter. Remove '%{key}' or check for typos."

  # --- AGENTS.md (agents_md.rs) ---
  agm_001:
    message: "Invalid markdown: %{description}"
    suggestion: "Fix the markdown syntax error -- check for unclosed tags, mismatched headers, or invalid link syntax"
  agm_002:
    # messages come from schemas::agents_md, not the validator directly
  agm_003:
    message: "%{filename} exceeds character limit (%{chars} chars, max %{limit} for Windsurf compatibility)"
    suggestion: "Split content into multiple files or reduce content length"
  agm_004:
    # messages come from schemas::agents_md, not the validator directly
  agm_005:
    suggestion: "Add a platform guard section header like '## %{platform} Specific' before platform-specific content"
  agm_006:
    # post-processing rule in lib.rs

  # --- XML (xml.rs) ---
  xml_001:
    message: "Unclosed XML tag '<%{tag}>'"
    suggestion: "Add closing tag '</%{tag}>'"
    fix: "Insert closing tag '</%{tag}>'"
  xml_002:
    message: "Expected '</%{expected}>' but found '</%{found}>'"
    suggestion: "Replace '</%{found}>' with '</%{expected}>'"
  xml_003:
    message: "Unmatched closing tag '</%{tag}>'"
    suggestion: "Remove '</%{tag}>' or add matching opening tag '<%{tag}>'"

  # --- Imports (imports.rs) ---
  cc_mem_001:
    not_found: "Import target not found: @%{path}"
    absolute: "Absolute import paths not allowed: @%{path}"
    escapes: "Import path escapes project root: @%{path}"
    absolute_suggestion: "Use relative paths only"
    escapes_suggestion: "Use relative paths that stay within the project root"
  cc_mem_002:
    message: "Circular import detected: %{chain}"
    suggestion: "Break the circular import chain to prevent infinite recursion"
  cc_mem_003:
    message: "Import depth exceeded (%{depth} levels, max %{max})"
    suggestion: "Flatten the import hierarchy to reduce depth"
  ref_001:
    not_found: "Import target not found: @%{path}"
  ref_002:
    message: "Broken markdown link: '%{url}' (file not found: %{resolved})"
    suggestion: "Fix the link target or remove the broken link"
  ref_003:
    message: "Duplicate @import: '%{path}' is imported multiple times"
    suggestion: "Remove the duplicate import to avoid processing the same file twice"
  ref_004:
    message: "Non-markdown @import: '%{path}' has extension '%{ext}'"
    suggestion: "Use .md files for @imports - non-markdown files may not be processed correctly"
  cache_poison:
    message: "Import cache lock was poisoned by a prior validator panic; recovered stale data"
    suggestion: "A validator panicked while holding the import cache lock. Validation continues with recovered data, but results may be stale."

  # --- Cross-platform (cross_platform.rs) ---
  xp_001:
    message: "Claude-specific feature '%{feature}' in %{filename}: %{description}"
    suggestion: "Move to CLAUDE.md or wrap in a Claude-specific section (e.g., '## Claude Code Specific')"
  xp_002:
    message: "%{filename} structure issue: %{issue}"
  xp_003:
    message: "Hard-coded %{platform} path '%{path}' may cause portability issues"
    suggestion: "Use environment variables or relative paths for better portability"
  xp_004:
    message: "Conflicting package managers: %{file1} uses %{mgr1} but %{file2} uses %{mgr2} for %{cmd_type} commands"
    suggestion: "Standardize on a single package manager across all instruction files"
  xp_005:
    message: "Conflicting tool constraints: '%{tool}' is allowed in %{allow_file} but disallowed in %{disallow_file}"
    suggestion: "Resolve the conflict by consistently allowing or disallowing the tool"
  xp_006:
    suggestion: "Document which file takes precedence (e.g., 'CLAUDE.md takes precedence over AGENTS.md')"
  xp_007:
    message: "AGENTS.md exceeds Codex CLI byte limit (%{bytes} bytes, max %{limit})"
    suggestion: "Reduce content or split into multiple files using @import for Codex CLI compatibility"
  xp_008:
    message: "CLAUDE.md contains Claude-specific feature '%{feature}' that Cursor cannot interpret: %{description}"
    suggestion: "Move Cursor-compatible instructions to .cursor/rules/ or guard Claude-specific content under a '## Claude Code' section header"

  # --- Copilot (copilot.rs) ---
  cop_001:
    message_empty: "Copilot instruction file is empty"
    message_no_content: "Copilot instruction file has no content after frontmatter"
    suggestion_empty: "Add meaningful instructions for Copilot to follow"
    suggestion_scoped_empty: "Add frontmatter with applyTo field and instructions"
  cop_002:
    message_missing: "Scoped Copilot instruction file missing required frontmatter"
    message_invalid_yaml: "Invalid YAML frontmatter: %{error}"
    message_missing_apply_to: "Scoped Copilot instruction file missing required 'applyTo' field"
    suggestion_add_frontmatter: "Add YAML frontmatter with --- markers and applyTo field"
    fix: "Insert template frontmatter with applyTo field"
    suggestion_fix_yaml: "Fix the YAML syntax in frontmatter"
    suggestion_add_apply_to: "Add 'applyTo: \"**/*.ts\"' or similar glob pattern"
  cop_003:
    message: "Invalid glob pattern '%{pattern}': %{error}"
    suggestion: "Use valid glob syntax like '**/*.ts' or 'src/**/*.js'"
  cop_004:
    message: "Unknown frontmatter key '%{key}' in Copilot instruction file"
    suggestion: "Remove unknown key '%{key}'. Only 'applyTo' and 'excludeAgent' are recognized."
  cop_005:
    message: "Invalid excludeAgent value '%{value}'. Valid values: 'code-review', 'coding-agent'"
    suggestion: "Use 'code-review' or 'coding-agent' for excludeAgent"
    fix: "Change excludeAgent to '%{fixed}'"
  cop_006:
    message: "Copilot instruction file exceeds recommended length (%{len} characters, limit ~4000)"
    suggestion: "Reduce content length or split into scoped instruction files"

  # --- Cursor (cursor.rs) ---
  cur_001:
    message_empty: "Cursor rule file is empty"
    message_no_content: "Cursor rule file has no content after frontmatter"
    suggestion_empty: "Add frontmatter with description and rules content"
    suggestion_no_content: "Add rules content after the frontmatter"
    suggestion_legacy_empty: "Add rules content to the file"
  cur_002:
    message: "Cursor .mdc file missing recommended frontmatter"
    suggestion: "Add YAML frontmatter with --- markers and description/globs fields"
    fix: "Insert template frontmatter with description and globs fields"
  cur_003:
    message: "Invalid YAML frontmatter: %{error}"
    suggestion: "Fix the YAML syntax in frontmatter"
  cur_004:
    message: "Invalid glob pattern '%{pattern}': %{error}"
    suggestion: "Use valid glob syntax like '**/*.ts' or 'src/**/*.js'"
  cur_005:
    message: "Unknown frontmatter key '%{key}' in Cursor rule file"
    suggestion: "Remove unknown key '%{key}'. Valid keys are: description, globs, alwaysApply."
  cur_006:
    message: "Legacy .cursorrules file detected - consider migrating to .cursor/rules/*.mdc format"
    suggestion: "Create .cursor/rules/ directory and add .mdc files with frontmatter for better organization"
    legacy_empty: "Cursor rules file is empty"
  cur_007:
    message: "alwaysApply is true but globs field is also set - globs are redundant"
    suggestion: "Remove the globs field since alwaysApply: true makes the rule apply to every chat session regardless of file patterns"
  cur_008:
    message: "alwaysApply must be a boolean (true/false), not a quoted string"
    suggestion: "Use alwaysApply: true or alwaysApply: false without quotes. YAML parses quoted values as strings."
    fix: "Convert '%{value}' to boolean %{fixed}"
  cur_009:
    message: "Agent-requested rule has no description - the agent cannot determine when to apply it"
    suggestion: "Add a description field explaining when this rule should apply, or set alwaysApply or globs to control activation"
  cur_010:
    message: ".cursor/hooks.json must define an integer version and a hooks object"
    missing_version: ".cursor/hooks.json is missing required integer field 'version'"
    missing_hooks: ".cursor/hooks.json is missing required object field 'hooks'"
    invalid_hooks: "Field 'hooks' must be an object, got %{got}"
    invalid_event_hooks: "hooks.%{event} must be an array of hook definitions, got %{got}"
    invalid_hook_entry: "hooks.%{event}[%{index}] must be an object"
    parse_error: "Failed to parse .cursor/hooks.json: %{error}"
    suggestion: "Define {\"version\": <integer>, \"hooks\": {\"eventName\": [{\"type\": \"command\", \"command\": \"...\"}]}}"
  cur_011:
    message: "Unknown Cursor hook event '%{event}'"
    suggestion: "Use one of the documented Cursor hook events in .cursor/hooks.json"
  cur_012:
    message: "hooks.%{event}[%{index}] is missing required non-empty string 'command' field"
    suggestion: "Set command to a non-empty string for each hook definition"
  cur_013:
    message: "hooks.%{event}[%{index}] has invalid 'type' value"
    suggestion: "If present, 'type' must be 'command' or 'prompt'"
  cur_014:
    message: "Cursor subagent file must have valid YAML frontmatter with required fields"
    invalid_frontmatter: "Cursor subagent frontmatter is invalid YAML or not a mapping"
    missing_name: "Cursor subagent frontmatter is missing required 'name' field"
    invalid_name: "Cursor subagent name must use lowercase letters, digits, and hyphens only"
    name_not_string: "Cursor subagent 'name' field must be a string"
    missing_description: "Cursor subagent frontmatter is missing required 'description' field"
    description_not_string: "Cursor subagent 'description' field must be a string"
    invalid_model: "Cursor subagent model must be 'fast', 'inherit', or a valid model ID"
    model_not_string: "Cursor subagent 'model' field must be a string"
    readonly_not_bool: "Cursor subagent 'readonly' field must be a boolean"
    is_background_not_bool: "Cursor subagent 'is_background' field must be a boolean"
    suggestion: "Use frontmatter fields: name, description, model, readonly, and is_background with valid types"
  cur_015:
    message: "Cursor subagent definition is empty after frontmatter"
    suggestion: "Add body instructions below the frontmatter section"
  cur_016:
    message: ".cursor/environment.json must be an object with install (required) and optional start, update, build, terminals"
    parse_error: "Failed to parse .cursor/environment.json: %{error}"
    install: "Field 'install' must be a string"
    missing_install: "Field 'install' is required and must be a string"
    start: "Field 'start' must be a string when present"
    update: "Field 'update' must be a string when present"
    invalid_build: "Field 'build' must be an object when present"
    build_dockerfile: "Field 'build.dockerfile' must be a string when present"
    build_context: "Field 'build.context' must be a string when present"
    invalid_terminals: "Field 'terminals' must be an array, got %{got}"
    terminal: "terminals[%{index}] must be an object with string fields 'name' and 'command'"
    terminal_not_object: "terminals[%{index}] must be a JSON object"
    suggestion: "Use schema: {\"install\":\"...\",\"start\":\"...\",\"build\":{\"dockerfile\":\"...\",\"context\":\"...\"},\"terminals\":[{\"name\":\"...\",\"command\":\"...\"}]}"

  # --- Cline (cline.rs) ---
  cln_001:
    message_empty: "Cline rules file is empty"
    message_no_content: "Cline rules file has no content after frontmatter"
    suggestion_empty: "Add rules content to the file"
    suggestion_no_content: "Add rules content after the frontmatter"
  cln_002:
    message: "Invalid glob pattern '%{pattern}': %{error}"
    suggestion: "Use valid glob syntax like '**/*.ts' or 'src/**/*.js'"
  cln_003:
    message: "Unknown frontmatter key '%{key}' in Cline rules file"
    suggestion: "Remove unknown key '%{key}'. Only 'paths' is a recognized frontmatter key."
  cln_004:
    message: "Cline ignores scalar paths values - use a YAML array instead"
    suggestion: "Change paths to array format: paths:\n  - \"%{pattern}\""
    fix: "Convert scalar paths to array format"

  # --- Gemini CLI (gemini_md.rs) ---
  gm_001:
    message: "Invalid markdown: %{description}"
    suggestion: "Fix the markdown syntax error -- check for unclosed tags, mismatched headers, or invalid link syntax"
  gm_002:
    message: "No markdown headers found in GEMINI.md instruction file"
    suggestion: "Add section headers (# Title, ## Section) for better organization"
  gm_003:
    message: "Missing project context section in GEMINI.md instruction file"
    suggestion: "Add a '# Project' or '## Overview' section describing the project purpose and tech stack"
  gm_004:
    message: "Invalid hooks configuration: %{description}"
    suggestion: "Check hook event names and required fields (type, command) in .gemini/settings.json"
    unknown_event: "Unknown hook event type '%{event}' in hooksConfig"
    missing_field: "Hook in '%{event}' is missing required field '%{field}'"
    invalid_type: "Hook type must be 'command', got '%{value}'"
    malformed_hook: "Malformed hook entry in '%{event}' - expected an object with 'type' and 'command' fields"
  gm_005:
    message: "Invalid extension manifest: %{description}"
    suggestion: "Ensure gemini-extension.json has required fields: name, version, description"
    missing_field: "Missing required field '%{field}'"
    invalid_name: "Extension name '%{name}' must be lowercase alphanumeric with dashes"
    parse_error: "Failed to parse gemini-extension.json: %{error}"
  gm_006:
    message: "Invalid .geminiignore: %{description}"
    suggestion: "Check .geminiignore syntax - use gitignore-style glob patterns"
    empty: ".geminiignore file is empty"
    syntax_error: "Invalid glob pattern on line %{line}: %{pattern}"
  gm_007:
    message: "@import references missing file: %{path}"
    suggestion: "Verify the import path exists relative to the GEMINI.md file location"
  gm_008:
    message: "Invalid context file name: %{description}"
    suggestion: "contextFileName should reference a valid file name (e.g., ending in .md)"
    path_not_filename: "contextFileName should be a filename, not a path"
  gm_009:
    message: "Failed to parse .gemini/settings.json: %{error}"
    suggestion: "Fix the JSON syntax error in .gemini/settings.json"
    unknown_key: "Unknown top-level key '%{key}' in .gemini/settings.json"

  # --- OpenCode (opencode.rs) ---
  oc_001:
    message: "Invalid share mode '%{value}'. Valid values: 'manual', 'auto', 'disabled'"
    type_error: "Field 'share' must be a string. Valid values: 'manual', 'auto', 'disabled'"
    suggestion: "Use 'manual', 'auto', or 'disabled' for the share field"
    fix: "Change share mode to '%{fixed}'"
  oc_002:
    not_found: "Instruction path '%{path}' does not exist"
    invalid_glob: "Instruction path '%{path}' has invalid glob syntax"
    traversal: "Instruction path '%{path}' must be relative and must not contain '..'"
    type_error: "Field 'instructions' must be an array of strings"
    suggestion: "Use relative paths that exist or valid glob patterns in the instructions array"
  oc_003:
    message: "opencode.json parse error: %{error}"
    suggestion: "Fix the JSON syntax in opencode.json"
  oc_004:
    message: "Unknown config key '%{key}' in opencode.json"
    suggestion: "Remove unrecognized keys or check the OpenCode documentation for valid configuration options"
  oc_006:
    message: "Remote instruction URL '%{url}' may slow startup (5-second timeout per URL)"
    suggestion: "Consider using local instruction files instead of remote URLs for faster startup"
  oc_007:
    message: "Custom agent '%{name}' is missing required field 'description'"
    type_error: "Field 'agent' must be an object mapping agent names to their configuration"
    suggestion: "Add a 'description' field to each custom agent definition"
  oc_008:
    message: "Invalid permission value '%{value}' for tool '%{tool}'. Valid values: 'allow', 'ask', 'deny'"
    type_error: "Field 'permission' must be an object or a string ('allow', 'ask', or 'deny')"
    suggestion: "Use 'allow', 'ask', or 'deny' for permission values"
  oc_009:
    message: "Invalid variable substitution '%{pattern}' - %{reason}"
    suggestion: "Use {env:VARIABLE_NAME} or {file:path/to/file} syntax for variable substitution"

  # --- Codex CLI (codex.rs) ---
  cdx_000:
    message: "Failed to parse .codex/config.toml as TOML: %{error}"
    suggestion: "Validate TOML syntax -- check for missing quotes, brackets, or invalid key-value pairs"
  cdx_001:
    message: "Invalid approvalMode '%{value}'. Valid values: 'suggest', 'auto-edit', 'full-auto'"
    type_error: "Field 'approvalMode' must be a string. Valid values: 'suggest', 'auto-edit', 'full-auto'"
    suggestion: "Use 'suggest', 'auto-edit', or 'full-auto' for the approvalMode field"
    fix: "Change approvalMode to '%{fixed}'"
  cdx_002:
    message: "Invalid fullAutoErrorMode '%{value}'. Valid values: 'ask-user', 'ignore-and-continue'"
    type_error: "Field 'fullAutoErrorMode' must be a string. Valid values: 'ask-user', 'ignore-and-continue'"
    suggestion: "Use 'ask-user' or 'ignore-and-continue' for the fullAutoErrorMode field"
    fix: "Change fullAutoErrorMode to '%{fixed}'"
  cdx_003:
    message: "AGENTS.override.md should not be in version control"
    suggestion: "Add AGENTS.override.md to .gitignore (it contains user-specific overrides)"
  cdx_004:
    message: "Unknown config key '%{key}' in .codex/config.toml"
    suggestion: "Remove unrecognized keys or check the Codex CLI documentation for valid configuration options"
  cdx_005:
    message: "project_doc_max_bytes value %{value} exceeds the maximum limit of 65536"
    type_error: "Field 'project_doc_max_bytes' must be a positive integer"
    suggestion: "Set project_doc_max_bytes to 65536 or less (default: 32768)"
  cdx_006:
    type_error: "Field 'project_doc_fallback_filenames' must be an array of strings"
    non_string: "Field 'project_doc_fallback_filenames' contains a non-string entry at index %{index}"
    empty: "Field 'project_doc_fallback_filenames' contains an empty filename at index %{index}"
    duplicate: "Field 'project_doc_fallback_filenames' contains duplicate filename '%{value}'"
    suspicious: "Field 'project_doc_fallback_filenames' contains path-like entry '%{value}'; use bare filenames only"
    suggestion: "Use a unique array of non-empty filenames like ['AGENTS.md', 'README.md']"
  cdx_cfg_001:
    message: "Invalid approval_policy '%{value}'. Valid values: 'untrusted', 'on-request', 'never', 'on-failure'"
    type_error: "Field 'approval_policy' must be a string"
    suggestion: "Use one of: 'untrusted', 'on-request', 'never', 'on-failure'"
  cdx_cfg_002:
    message: "Invalid sandbox_mode '%{value}'. Valid values: 'read-only', 'workspace-write', 'danger-full-access'"
    type_error: "Field 'sandbox_mode' must be a string"
    suggestion: "Use one of: 'read-only', 'workspace-write', or 'danger-full-access'"
  cdx_cfg_003:
    message: "Invalid model_reasoning_effort '%{value}'. Valid values: 'none', 'minimal', 'low', 'medium', 'high', 'xhigh'"
    type_error: "Field 'model_reasoning_effort' must be a string"
    suggestion: "Use one of: 'none', 'minimal', 'low', 'medium', 'high', 'xhigh'"
  cdx_cfg_004:
    message: "Invalid model_verbosity '%{value}'. Valid values: 'low', 'medium', 'high'"
    type_error: "Field 'model_verbosity' must be a string"
    suggestion: "Use one of: 'low', 'medium', 'high'"
  cdx_cfg_005:
    message: "Invalid personality '%{value}'. Valid values: 'none', 'friendly', 'pragmatic'"
    type_error: "Field 'personality' must be a string"
    suggestion: "Use one of: 'none', 'friendly', 'pragmatic'"
  cdx_cfg_006:
    message: "Unknown Codex config field '%{key}'"
    suggestion: "Remove unsupported keys or verify spelling against the official Codex config schema"
  cdx_cfg_007:
    message: "sandbox_mode is set to danger-full-access without explicit warning acknowledgment"
    suggestion: "Set [notice].hide_full_access_warning = true only after explicitly reviewing the risk"
  cdx_cfg_008:
    message: "Invalid shell environment inherit mode '%{value}'. Valid values: 'core', 'all', 'none'"
    type_error: "shell_environment_policy.inherit must be a string"
    suggestion: "Use one of: 'core', 'all', 'none'"
  cdx_cfg_009:
    type_error: "Field 'mcp_servers' must be an object mapping server names to server config objects"
    invalid_server: "MCP server '%{server}' must be an object"
    missing_transport: "MCP server '%{server}' must define either a non-empty 'command' or 'url'"
    suggestion: "Define each MCP server as an object with a command or URL transport"
  cdx_cfg_010:
    message: "Potential hardcoded secret in config field '%{key}'"
    suggestion: "Use environment variable references instead of embedding secrets in config"
  cdx_cfg_011:
    message: "Unknown feature flag '%{key}' under [features]"
    type_error: "Field 'features' must be an object"
    suggestion: "Remove unsupported feature flags or verify the feature name against Codex docs"
  cdx_cfg_012:
    message: "Invalid cli_auth_credentials_store '%{value}'. Valid values: 'file', 'keyring', 'auto', 'ephemeral'"
    type_error: "Field 'cli_auth_credentials_store' must be a string"
    suggestion: "Use one of: 'file', 'keyring', 'auto', 'ephemeral'"
  cdx_ag_001:
    message: "AGENTS.md is empty"
    suggestion: "Add concrete repository-specific operating instructions"
  cdx_ag_002:
    message: "Potential secret detected in AGENTS.md"
    suggestion: "Remove hardcoded credentials and reference environment variables instead"
  cdx_ag_003:
    message: "AGENTS.md appears overly generic and may not provide actionable project guidance"
    suggestion: "Add repository-specific commands, paths, and guardrails"
  cdx_app_001:
    message: "Invalid default_tools_approval_mode '%{value}' for app '%{app}'. Valid values: 'auto', 'prompt', 'approve'"
    type_error: "default_tools_approval_mode for app '%{app}' must be a string"
    suggestion: "Use one of: 'auto', 'prompt', 'approve'"

  # --- Windsurf (windsurf.rs) ---
  ws_001:
    message: "Windsurf rule file is empty"
    suggestion: "Add rule content to the file"
  ws_002:
    message: "Windsurf rule file exceeds %{limit} character limit (%{len} characters)"
    suggestion: "Reduce content length or split into multiple rule files"
  ws_003_empty:
    message: "Windsurf workflow file is empty"
    suggestion: "Add workflow steps to the file"
  ws_003_too_long:
    message: "Windsurf workflow file exceeds %{limit} character limit (%{len} characters)"
    suggestion: "Reduce content length or split into multiple workflow files"
  ws_004:
    message: "Legacy .windsurfrules file detected"
    suggestion: "Migrate to .windsurf/rules/ directory with individual .md files"

  # --- Kiro Steering (kiro_steering.rs) ---
  kiro_001:
    message: "Invalid steering file inclusion mode '%{value}' - valid modes are: always, fileMatch, manual, auto"
    suggestion: "Use one of: always, fileMatch, manual, auto"
  kiro_002_auto:
    message: "Steering file with 'auto' inclusion mode is missing required field '%{field}'"
    suggestion: "Add both 'name' and 'description' fields when using inclusion: auto"
  kiro_002_filematch:
    message: "Steering file with 'fileMatch' inclusion mode is missing required 'fileMatchPattern' field"
    suggestion: "Add a 'fileMatchPattern' glob pattern (e.g., fileMatchPattern: '**/*.ts')"
  kiro_003:
    message: "Invalid fileMatchPattern glob: %{error}"
    suggestion: "Fix the glob pattern syntax"
  kiro_004:
    message: "Kiro steering file is empty"
    suggestion: "Add steering content to the file"
  kiro_005:
    message: "Kiro steering file has frontmatter but no instruction body"
    suggestion: "Add meaningful steering instructions below the frontmatter"
  kiro_006:
    message: "Potential secret detected in Kiro steering content (%{marker})"
    suggestion: "Remove hardcoded credentials and reference environment variables instead"
  kiro_007:
    message: "fileMatchPattern is present but inclusion is '%{inclusion}' instead of 'fileMatch'"
    suggestion: "Set inclusion: fileMatch or remove fileMatchPattern"
  kiro_008:
    message: "Unknown Kiro steering frontmatter field '%{field}'"
    suggestion: "Use only supported fields: inclusion, name, description, fileMatchPattern"
  kiro_009:
    message: "Inline file reference points to a missing file: %{reference}"
    suggestion: "Fix the reference path or create the referenced file"
  kr_pw_001:
    message: "POWER.md is missing required frontmatter fields: %{fields}"
    suggestion: "Add required frontmatter fields: name, description, keywords"
  kr_pw_001_parse:
    message: "POWER.md frontmatter is invalid YAML: %{error}"
    suggestion: "Fix YAML syntax in POWER.md frontmatter"
  kr_pw_002:
    message: "POWER.md keywords array is empty"
    suggestion: "Add one or more activation keywords to POWER.md"
  kr_pw_003:
    message: "POWER.md body is empty"
    suggestion: "Add onboarding/workflow/reference guidance to POWER.md body"
  kr_pw_004:
    message: "Adjacent power mcp.json has invalid mcpServers structure"
    suggestion: "Ensure mcp.json uses an object mcpServers map with valid server entries"
  kr_ag_001:
    message: "Unknown field '%{field}' in Kiro agent JSON"
    suggestion: "Remove unsupported fields or use documented Kiro agent keys"
  kr_ag_002:
    message: "Invalid Kiro agent resource entry: %{resource}"
    suggestion: "Use file://, skill://, or object entries with type: knowledgeBase"
  kr_ag_003:
    message: "allowedTools contains '%{tool}' which is not present in tools"
    suggestion: "Keep allowedTools as a subset of tools"
  kr_ag_004:
    message: "Invalid Kiro agent model value '%{model}'"
    suggestion: "Use a documented model value (claude-sonnet-4, claude-sonnet4.5, claude-sonnet-4-5, claude-opus4.5, claude-opus-4-5, Auto)"
  kr_ag_005:
    message: "Kiro agent has includeMcpJson: false and no inline mcpServers"
    suggestion: "Enable includeMcpJson or configure inline mcpServers for MCP access"
  kr_ag_006:
    message: "Kiro agent references unknown subagent '@%{agent}'"
    suggestion: "Create .kiro/agents/%{agent}.json or remove the subagent reference"
  kr_ag_007:
    message: "Kiro agent has broader tools than referenced subagent '@%{agent}' (extra tools: %{extra_tools})"
    suggestion: "Narrow this agent's tool scope or align '@%{agent}' tool permissions"
  kr_hk_001:
    message: "Invalid Kiro IDE hook event '%{event}'"
    suggestion: "Use one of: fileEdited, fileCreate, fileDelete, promptSubmit, agentStop, preToolUse, postToolUse, manual"
  kr_hk_001_parse:
    message: "Kiro IDE hook file has invalid JSON structure: %{error}"
    suggestion: "Fix JSON syntax in the hook file before configuring event/actions"
  kr_hk_002:
    message: "Kiro file hook for event '%{event}' is missing patterns"
    suggestion: "Add patterns for fileEdited/fileCreate/fileDelete hooks"
  kr_hk_003:
    message: "Kiro IDE hook is missing both runCommand and askAgent action"
    suggestion: "Configure runCommand or askAgent (top-level or under then)"
  kr_hk_004:
    message: "Kiro '%{event}' hook is missing toolTypes filter"
    suggestion: "Add toolTypes to scope preToolUse/postToolUse hooks"
  kr_hk_005:
    message: "Invalid Kiro CLI hook event key '%{event}' in agent JSON"
    suggestion: "Use one of: agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop"
  kr_hk_006:
    message: "Kiro CLI hook entry at %{event}[%{index}] is missing required command"
    suggestion: "Add a non-empty command to each CLI hook entry"
  kr_mcp_001:
    message: "Kiro MCP server '%{server}' is missing both command and url"
    suggestion: "Set command for local servers or url for remote servers"
  kr_mcp_001_root:
    message: "Kiro MCP config is missing mcpServers object"
    suggestion: "Define mcpServers as an object with one or more server entries"
  kr_mcp_001_parse:
    message: "Kiro MCP config has invalid JSON structure: %{error}"
    suggestion: "Fix JSON syntax and ensure mcpServers is an object"
  kr_mcp_002:
    message: "Kiro MCP server '%{server}' has potential hardcoded secret in env '%{env_key}'"
    suggestion: "Use environment variable indirection such as ${VAR_NAME} instead of plaintext secrets"
  kr_mcp_006:
    message: "Kiro MCP server '%{server}' has invalid oauth.clientId configuration: %{reason}"
    suggestion: "Use oauth.clientId as a non-empty string only on HTTP(S) remote MCP servers, or remove the oauth block"
    reasons:
      oauth_object: "'oauth' must be an object"
      missing_client_id: "'oauth.clientId' is required when 'oauth' is configured"
      client_id_string: "'oauth.clientId' must be a string"
      client_id_non_empty: "'oauth.clientId' must not be empty"
      http_url: "'oauth.clientId' can only be used with HTTP(S) remote MCP server URLs"

  # --- Prompt engineering (prompt.rs) ---
  pe_001:
    message: "Critical keyword '%{keyword}' at %{percent} percent of document (40-60 percent is the 'lost in the middle' zone)"
    suggestion: "Move critical content to the start or end of the document for better recall"
  pe_002:
    message: "Chain-of-thought phrase '%{phrase}' used with simple task '%{task}'"
    suggestion: "Remove chain-of-thought instructions for simple tasks; CoT can hurt performance on direct operations"
  pe_003:
    message: "Weak language '%{term}' in critical section '%{section}'"
    suggestion: "Use strong language (must/always/never) in critical sections for better compliance"
  pe_004:
    message: "Ambiguous term '%{term}' creates unclear instruction"
    suggestion: "Replace with specific criteria or remove ambiguity (e.g., 'always' instead of 'usually')"
  pe_005:
    message: "Redundant instruction '%{phrase}' - LLMs already follow this by default"
    suggestion: "Remove generic instructions and focus on project-specific behavior and constraints"
  pe_006:
    message: "Negative instruction '%{text}' without positive alternative"
    suggestion: "Add a positive alternative after negative instructions (e.g., 'Instead, use...')"

  # --- Plugin (plugin.rs) ---
  cc_pl_001:
    message: "plugin.json must be located in .claude-plugin/ directory"
    suggestion: "Move plugin.json to .claude-plugin/plugin.json"
  cc_pl_002:
    message: "Component '%{component}' must not be inside .claude-plugin/"
    suggestion: "Move components to the plugin root directory"
  cc_pl_003:
    message: "Invalid semver format: '%{version}'"
    suggestion: "Use semver format: 1.0.0, 1.0.0-rc.1, 1.0.0+build"
  cc_pl_004:
    message: "Missing or invalid required field: %{field}"
    suggestion: "Add '%{field}' field to plugin.json"
  cc_pl_004_recommended:
    message: "Missing or invalid recommended field: %{field}"
    suggestion: "Consider adding '%{field}' field to plugin.json"
  cc_pl_005:
    message: "Plugin name must not be empty"
    suggestion: "Set a non-empty plugin name"
  cc_pl_006:
    message: "Failed to parse plugin.json: %{error}"
    suggestion: "Validate JSON syntax in plugin.json -- check for missing commas, brackets, or unquoted keys"
  cc_pl_007:
    message: "Invalid component path in '%{field}': '%{path}' must be relative (no absolute paths or '..' traversal)"
    suggestion: "Use a relative path starting with './' (e.g., './skills/')"
  cc_pl_008:
    message: "Component path in '%{field}' points inside .claude-plugin/: '%{path}'"
    suggestion: "Move the component to the plugin root directory and update the path"
  cc_pl_009:
    message: "Invalid author object: 'author.name' must be a non-empty string"
    suggestion: "Set 'author.name' to a non-empty string"
  cc_pl_010:
    message: "Invalid homepage URL: '%{url}' must use http:// or https:// scheme"
    suggestion: "Use a valid URL with http:// or https:// scheme"
  cc_pl_015:
    message: "Default component folder '%{component}' exists but plugin.json overrides '%{component}' without including './%{component}'"
    suggestion: "Add './%{component}' to '%{component}' or move those files into the configured component path"

  # --- Codex Plugin (codex_plugin.rs) ---
  cdx_pl_001:
    message: "plugin.json must be located in .codex-plugin/ directory"
    suggestion: "Move plugin.json to .codex-plugin/plugin.json"
  cdx_pl_002:
    message: "Failed to parse plugin.json: %{error}"
    suggestion: "Validate JSON syntax in plugin.json - check for missing commas, brackets, or unquoted keys"
  cdx_pl_003:
    message: "Missing or empty plugin name"
    suggestion: "Add a 'name' field with a non-empty string to plugin.json"
  cdx_pl_004:
    message: "Invalid plugin name '%{name}' - must be ASCII alphanumeric, hyphens, or underscores only"
    suggestion: "Rename to use only ASCII letters, digits, hyphens, and underscores"
  cdx_pl_005:
    message: "Component path '%{path}' in '%{field}' must start with ./"
    suggestion: "Prepend './' to the path"
  cdx_pl_006:
    message: "Component path '%{path}' in '%{field}' uses '..' traversal"
    suggestion: "Remove directory traversal from the path"
  cdx_pl_007:
    message: "Component path '%{path}' in '%{field}' is bare './' (empty relative path)"
    suggestion: "Specify a non-empty relative path after './'"
  cdx_pl_008:
    message: "defaultPrompt has %{count} entries but maximum is 3"
    suggestion: "Remove excess defaultPrompt entries (maximum 3 allowed)"
  cdx_pl_009:
    message: "defaultPrompt entry exceeds 128 characters (%{length} chars)"
    suggestion: "Shorten the prompt to 128 characters or fewer"
  cdx_pl_010:
    message: "defaultPrompt entry is empty after whitespace normalization"
    suggestion: "Remove empty defaultPrompt entries or add content"
  cdx_pl_011:
    message: "Invalid URL '%{url}' in interface.%{field}"
    suggestion: "Use a valid http:// or https:// URL"
  cdx_pl_012:
    message: "Asset path '%{path}' in interface.%{field} must start with ./ and not use '..' traversal"
    suggestion: "Use a relative path starting with './' within the plugin root"
  cdx_pl_013:
    message: "'hooks' field is not supported in Codex plugin manifests"
    suggestion: "Remove the 'hooks' field from plugin.json"
  cdx_pl_014:
    message: "Missing 'description' field - recommended for marketplace visibility"
    suggestion: "Add a 'description' string to plugin.json for better discoverability"

  # --- Roo Code (roo.rs) ---
  roo_001:
    message: "Roo Code rule file is empty"
    suggestion: "Add rule content to the file"
  roo_002:
    parse_error: "Failed to parse .roomodes: %{error}"
    suggestion: "Fix the JSON syntax in .roomodes"
    missing_custom_modes: ".roomodes file is missing required 'customModes' field"
    custom_modes_type: "'customModes' field must be an array"
    missing_slug: "Custom mode at %{position} is missing required 'slug' field"
    invalid_slug: "Invalid slug '%{slug}' in %{position} - must be lowercase alphanumeric with hyphens"
    duplicate_slug: "Duplicate slug '%{slug}' in %{position}"
    missing_name: "Custom mode at %{position} is missing required 'name' field"
    missing_role_definition: "Custom mode at %{position} is missing required 'roleDefinition' field"
    missing_groups: "Custom mode '%{slug}' is missing required 'groups' field"
    groups_type: "Custom mode '%{slug}' has invalid 'groups' field - must be an array"
    invalid_group: "Invalid group '%{group}' in %{position}. Valid groups: %{valid}"
  roo_003:
    empty: ".rooignore file is empty"
    suggestion: "Add glob patterns to .rooignore or remove the file"
    invalid_pattern: "Invalid glob pattern on line %{line}: %{pattern}"
  roo_004:
    message: "Invalid mode slug '%{slug}' in directory name"
    suggestion: "Use lowercase alphanumeric characters and hyphens only (e.g., 'my-custom-mode')"
  roo_005:
    parse_error: "Failed to parse .roo/mcp.json: %{error}"
    suggestion: "Fix the JSON syntax in .roo/mcp.json"
    missing_mcp_servers: ".roo/mcp.json is missing required 'mcpServers' field"
    mcp_servers_type: "'mcpServers' field must be an object"
    invalid_server_entry: "Server '%{server}' must be an object with configuration fields"
    missing_command: "Server '%{server}' is missing required 'command' field for stdio type"
    missing_url: "Server '%{server}' is missing required 'url' field for http/sse type"
  roo_006:
    message: "Mode slug '%{slug}' is not a built-in mode and not defined in .roomodes"
    suggestion: "Add the custom mode definition to .roomodes or use a built-in mode slug (code, architect, ask, debug, orchestrator)"

  # --- Version (lib.rs) ---
  ver_001:
    message: "No tool or spec versions pinned. Version-dependent rules will use default assumptions."
    suggestion: "Pin versions in .agnix.toml [tool_versions] or [spec_revisions] for deterministic validation."

  # --- File-level errors (lib.rs / pipeline.rs) ---
  file_read_error: "Failed to validate file: %{error}"
  file_read_error_suggestion: "Check file permissions and ensure the file is not locked by another process"
  xp_004_read_error: "Failed to read instruction file: %{error}"
  xp_004_read_error_suggestion: "Check file permissions and ensure the file exists and is readable"
  invalid_glob_pattern: "Ignoring invalid glob pattern '%{pattern}': %{error}"
  invalid_glob_pattern_suggestion: "Fix the glob pattern syntax. Use standard glob characters: *, **, ?, [abc]"

# ===========================================================================
# Core - Config warnings, eval output, LintError
# ===========================================================================
core:
  error:
    file_read: "Failed to read file: %{path}"
    file_write: "Failed to write file: %{path}"
    file_symlink: "Refusing to read symlink: %{path}"
    file_too_big: "File too large: %{path} (%{size} bytes, limit %{limit} bytes)"
    file_not_regular: "Not a regular file: %{path}"
    invalid_exclude: "Invalid exclude pattern: %{pattern} (%{message})"
    invalid_include: "Invalid include pattern: %{pattern} (%{message})"
  config:
    unknown_rule: "Unknown rule ID pattern '%{rule}'. Expected prefix: %{prefixes}"
    unknown_rule_suggestion: "Check the rule ID spelling or remove if invalid"
    unknown_tool: "Unknown tool '%{tool}'. Valid tools: %{valid}"
    unknown_tool_suggestion: "Use one of the supported tool names"
    deprecated_target: "Field 'target' is deprecated"
    deprecated_target_suggestion: "Use the 'tools' array instead"
    deprecated_mcp_version: "Field 'mcp_protocol_version' is deprecated"
    deprecated_mcp_version_suggestion: "Use 'spec_revisions.mcp_protocol' instead"
    invalid_files_pattern: "Invalid files pattern '%{pattern}': %{message}"
    invalid_files_pattern_suggestion: "Fix the glob pattern syntax. Valid examples: 'docs/ai-rules/*.md', '**/*.rules.md'"
    files_path_traversal: "Pattern '%{pattern}' contains path traversal ('../'). Patterns must be relative to project root without parent references."
    files_path_traversal_suggestion: "Remove '../' from the pattern and use a path relative to the project root"
    files_absolute_path: "Pattern '%{pattern}' uses an absolute path. Patterns must be relative to the project root."
    files_absolute_path_suggestion: "Remove the leading '/' or drive letter and use a relative path"
    files_pattern_count_limit: "Field '%{field}' has %{count} patterns, which exceeds the recommended limit of %{limit}."
    files_pattern_count_limit_suggestion: "Consider consolidating patterns or using broader glob expressions"
    load_warning: "Failed to parse config '%{path}': %{error}. Using defaults."

# ===========================================================================
# CLI - Command-line interface output strings
# ===========================================================================
cli:
  validating: "Validating:"
  no_issues_found: "No issues found"
  found_errors_warnings: "Found %{errors} %{error_word}, %{warnings} %{warning_word}"
  info_messages: "  %{count} info messages"
  fixable_issues: "  %{count} %{word} automatically fixable"
  issue_is: "issue is"
  issues_are: "issues are"
  error_singular: "error"
  error_plural: "errors"
  warning_singular: "warning"
  warning_plural: "warnings"
  hint_run_fix: "Run with %{flag} to apply fixes"
  applying_fixes: "%{mode} fixes%{safe_mode}..."
  no_fixes: "  No fixes to apply"
  would_fix: "Would fix:"
  fixed: "Fixed:"
  diff_label: "Diff"
  fix_summary: "%{action} %{count} %{word}"
  file_singular: "file"
  file_plural: "files"
  preview: "Preview"
  applying: "Applying"
  safe_only: " (safe only)"
  created: "Created:"
  schema_written: "Schema written to:"
  error_label: "Error:"
  warning_label: "Warning:"
  config_warning_label: "Config warning:"
  hint_label: "hint:"
  rule_label: "rule:"
  metadata_label: "Metadata:"
  category_label: "Category:"
  severity_label: "Severity:"
  tool_label: "Tool:"
  generic_tool: "generic"
  help_label: "help:"
  note_label: "note:"
  fix_label: "fix:"
  safe: "safe"
  unsafe: "unsafe"
  fixable: "[fixable]"
  watch_error_text_only: "Watch mode is only supported with text output."
  watch_error_fix: "Watch mode cannot be combined with fix flags."
  fix_error_text_only: "Fix flags are only supported with text output. Remove --format or use --format text."
  evaluating: "Evaluating:"
  filter_label: "  filter:"
  per_case_results: "Per-Case Results"
  pass: "PASS"
  fail: "FAIL"
  unexpected_label: "unexpected:"
  missing_label: "missing:"
  success: "SUCCESS"
  failed: "FAILED"
  all_cases_passed: "All %{count} cases passed"
  cases_failed: "%{failed}/%{total} cases failed"
  telemetry_status: "Telemetry Status"
  telemetry_configured: "Configured:"
  telemetry_effective: "Effective:"
  telemetry_enabled: "enabled"
  telemetry_disabled: "disabled"
  telemetry_env_note: "Telemetry is disabled due to environment (CI, DO_NOT_TRACK, etc.)"
  telemetry_installation_id: "Installation ID:"
  telemetry_consent_given: "Consent given:"
  telemetry_privacy: "Privacy Guarantees"
  telemetry_privacy_1: "  - Opt-in only (disabled by default)"
  telemetry_privacy_2: "  - No file paths or contents ever collected"
  telemetry_privacy_3: "  - No user identity collected"
  telemetry_privacy_4: "  - Only aggregate counts (file types, rule triggers)"
  telemetry_privacy_5: "  - Respects DO_NOT_TRACK, CI environments"
  telemetry_config_file: "Config file:"
  telemetry_already_enabled: "Telemetry is already enabled."
  telemetry_ok_enabled: "Telemetry enabled."
  telemetry_thanks: "Thank you for helping improve agnix!"
  telemetry_collect: "What we collect:"
  telemetry_collect_1: "  - File type counts (e.g., 5 skills, 2 MCP configs)"
  telemetry_collect_2: "  - Rule trigger counts (e.g., AS-001: 3 times)"
  telemetry_collect_3: "  - Error/warning counts"
  telemetry_collect_4: "  - Validation duration"
  telemetry_never_collect: "What we never collect:"
  telemetry_never_1: "  - File paths or names"
  telemetry_never_2: "  - File contents or code"
  telemetry_never_3: "  - User identity"
  telemetry_disable_hint: "You can disable telemetry at any time with: %{cmd}"
  telemetry_already_disabled: "Telemetry is already disabled."
  telemetry_ok_disabled: "Telemetry disabled."
  locale_unsupported: "Warning: unsupported locale '%{locale}', falling back to 'en'"
  watch_starting: "Starting watch mode. Press Ctrl+C to stop."
  watch_changes_detected: "Changes detected. Re-validating..."
  watch_error: "Watch error: %{error}"
  watch_stopped: "Watch mode stopped."

# ===========================================================================
# LSP - Language server protocol strings
# ===========================================================================
lsp:
  suggestion_label: "Suggestion:"
  hover:
    name: "Name"
    description: "Description"
    model: "Model"
    context: "Context"
    agent: "Agent"
    allowed_tools: "Allowed Tools"
    argument_hint: "Argument Hint"
    user_invocable: "User Invocable"
    disable_model_invocation: "Disable Model Invocation"
    license: "License"
    compatibility: "Compatibility"
