[
  {
    "command": "give",
    "description": "Gives items to players",
    "je_syntax": ["give <targets> <item> [<count>]"],
    "arguments": {
      "targets": {"type": "entity", "description": "Player name, target selector, or UUID. Must resolve to players."},
      "item": {"type": "item_stack", "description": "Item ID with optional data components: item_id[component=value]. Since 1.20.5, uses data components instead of NBT."},
      "count": {"type": "integer", "description": "Number of items (1-2147483647). Defaults to 1."}
    },
    "examples": {
      "basic": "give @p minecraft:diamond_sword 1",
      "with_enchantments": "give @p minecraft:diamond_sword[enchantments={sharpness:5,unbreaking:3}] 1",
      "with_lore": "give @p minecraft:diamond_sword[lore=[\"Example\"]] 1",
      "with_potion": "give @a minecraft:potion[potion_contents={potion:\"minecraft:night_vision\"}] 1",
      "spawn_egg_override": "give @p minecraft:wolf_spawn_egg[entity_data={id:\"minecraft:cat\"}] 1",
      "custom_max_stack": "give @s minecraft:totem_of_undying[max_stack_size=64] 2304"
    },
    "version_notes": "1.20.5+: NBT data tags replaced with data components. Old format: give @p diamond_sword{Enchantments:[{id:sharpness,lvl:5}]}. New format: give @p diamond_sword[enchantments={sharpness:5}].",
    "common_errors": [
      "Missing minecraft: namespace prefix (give @p diamond 1 -> give @p minecraft:diamond 1)",
      "Transposed arguments: give @p 64 diamond -> give @p minecraft:diamond 64",
      "Old NBT enchantment format: {Enchantments:[...]} is invalid in 1.21+",
      "Using 'wood' instead of 'oak_log', 'food' instead of specific item ID"
    ]
  },
  {
    "command": "effect",
    "description": "Adds or removes status effects from entities",
    "je_syntax": [
      "effect give <targets> <effect> [<seconds>] [<amplifier>] [<hideParticles>]",
      "effect give <targets> <effect> infinite [<amplifier>] [<hideParticles>]",
      "effect clear [<targets>] [<effect>]"
    ],
    "arguments": {
      "targets": {"type": "entity", "description": "Player name, target selector, or UUID."},
      "effect": {"type": "resource", "description": "Effect ID with minecraft: namespace (e.g. minecraft:speed, minecraft:resistance)."},
      "seconds": {"type": "integer", "description": "Duration in seconds (0-1000000). Defaults to 30. For instant effects, duration is in game ticks."},
      "amplifier": {"type": "integer", "description": "Effect level minus 1 (0-255). 0 = level I, 1 = level II, etc. Defaults to 0."},
      "hideParticles": {"type": "bool", "description": "Whether to hide particles and HUD indicator. Defaults to false."}
    },
    "examples": {
      "basic_speed": "effect give @p minecraft:speed 60 1",
      "resistance_hidden": "effect give @s minecraft:resistance 1000000 4 true",
      "clear_all": "effect clear @a",
      "clear_specific": "effect clear @a minecraft:haste",
      "infinite_duration": "effect give @p minecraft:night_vision infinite 0"
    },
    "version_notes": "Since 1.13, syntax split into 'effect give' and 'effect clear'. Bare 'effect <player> <effect>' without 'give' is INVALID.",
    "common_errors": [
      "Missing 'give' subcommand: 'effect @p speed 60' is invalid. Must be 'effect give @p minecraft:speed 60'",
      "Inventing effects: 'invulnerability' does not exist. Use resistance 4 + regeneration 2 + absorption 4 instead",
      "Missing minecraft: prefix on effect ID"
    ]
  },
  {
    "command": "tp",
    "aliases": ["teleport"],
    "description": "Teleports entities to positions or other entities",
    "je_syntax": [
      "tp <destination>",
      "tp <targets> <destination>",
      "tp <location>",
      "tp <targets> <location>",
      "tp <targets> <location> <rotation>",
      "tp <targets> <location> facing <facingLocation>",
      "tp <targets> <location> facing entity <facingEntity> [<facingAnchor>]"
    ],
    "arguments": {
      "targets": {"type": "entity", "description": "Entity/entities to teleport. If omitted, defaults to command executor."},
      "destination": {"type": "entity", "description": "Entity to teleport to. Must resolve to single entity."},
      "location": {"type": "vec3", "description": "X Y Z coordinates. Supports ~ (relative) and ^ (local/caret) notation."},
      "rotation": {"type": "rotation", "description": "Yaw and pitch in degrees. Yaw: -180=north, -90=east, 0=south, 90=west."},
      "facingLocation": {"type": "vec3", "description": "Coordinates to face after teleporting."},
      "facingEntity": {"type": "entity", "description": "Entity to face after teleporting."},
      "facingAnchor": {"type": "entity_anchor", "description": "eyes or feet. Defaults to feet."}
    },
    "examples": {
      "to_player": "tp @s Alice",
      "all_to_self": "tp @a @s",
      "to_coords": "tp @s 100 64 -200",
      "relative": "tp @s ~ ~3 ~",
      "forward_one_block": "tp @s ^ ^ ^1",
      "cross_dimension": "execute in minecraft:the_nether run tp @s ~ ~ ~"
    },
    "version_notes": "Since 1.13, /tp is an alias for /teleport with identical syntax. Coordinates are relative to executor for both.",
    "common_errors": [
      "Using 'execute as' instead of 'execute at' for relative coordinates -- 'as' changes executor but not position context",
      "Teleporting ~100 up without slow_falling -- causes fall damage",
      "Using tp in benevolent responses when player didn't ask to move"
    ]
  },
  {
    "command": "execute",
    "description": "Executes commands with modified context (executor, position, conditions)",
    "je_syntax": [
      "execute align <axes> -> execute",
      "execute anchored <anchor> -> execute",
      "execute as <targets> -> execute",
      "execute at <targets> -> execute",
      "execute facing (<pos>|entity <targets> <anchor>) -> execute",
      "execute in <dimension> -> execute",
      "execute on <relation> -> execute",
      "execute positioned (<pos>|as <targets>|over <heightmap>) -> execute",
      "execute rotated (<rot>|as <targets>) -> execute",
      "execute store (result|success) ... -> execute",
      "execute summon <entity> -> execute",
      "execute (if|unless) ... -> [execute]",
      "execute run <command>"
    ],
    "key_subcommands": {
      "as": "Changes executor (@s) but NOT position. Use for targeting entities.",
      "at": "Changes execution position, rotation, AND dimension to match entity. Use for relative coordinates.",
      "positioned": "Changes only position. Does not change rotation or dimension.",
      "if/unless block": "Tests block at position. 'execute if block X Y Z minecraft:stone'",
      "if/unless entity": "Tests entity existence. 'execute if entity @e[type=zombie,distance=..10]'",
      "run": "Executes the final command. Must be last in the chain."
    },
    "examples": {
      "at_player": "execute at slingshooter08 run fill ~-5 ~-1 ~-5 ~5 ~-1 ~5 minecraft:stone",
      "as_all_entities": "execute as @e[type=sheep] at @s run tp @s ~ ~1 ~",
      "conditional": "execute if entity @e[type=zombie,distance=..10] run say Zombies nearby!",
      "cross_dimension": "execute in minecraft:the_nether run locate structure minecraft:fortress",
      "block_check": "execute if block 0 64 0 minecraft:grass_block run say Found grass"
    },
    "version_notes": "Since 1.13, completely restructured with subcommand chains. Old 'execute <entity> ~ ~ ~ <command>' format is invalid.",
    "common_errors": [
      "'execute as <player> run fill ~ ~ ~ ...' -- 'as' does NOT set position. Relative coords resolve to server/console origin, not the player. Use 'execute at' or 'execute as <player> at @s'",
      "Unnecessary nesting: 'execute as X run execute positioned ~ ~ ~ run ...' can be simplified to 'execute at X run ...'",
      "'execute as X run gameMode creative' -- 'as' is unnecessary for commands that take a player argument directly"
    ]
  },
  {
    "command": "weather",
    "description": "Sets the weather",
    "je_syntax": ["weather (clear|rain|thunder) [<duration>]"],
    "arguments": {
      "type": {"type": "literal", "description": "One of: clear, rain, thunder. NO other values (storm, rainstorm, thunderstorm are INVALID)."},
      "duration": {"type": "integer", "description": "Duration in seconds (0-1000000). Defaults to random 6000-18000 ticks (300-900 seconds)."}
    },
    "examples": {
      "clear": "weather clear",
      "rain": "weather rain",
      "thunder": "weather thunder",
      "timed": "weather rain 600"
    },
    "version_notes": "No significant changes in 1.21.",
    "common_errors": [
      "'weather storm' is INVALID -- use 'weather thunder'",
      "'weather rainstorm' is INVALID -- use 'weather thunder'",
      "'weather thunderstorm' is INVALID -- use 'weather thunder'"
    ]
  },
  {
    "command": "gamemode",
    "description": "Sets a player's game mode",
    "je_syntax": ["gamemode <gamemode> [<target>]"],
    "arguments": {
      "gamemode": {"type": "gamemode", "description": "One of: survival, creative, adventure, spectator. Full words only, not abbreviations."},
      "target": {"type": "entity", "description": "Player(s) to change. Defaults to executor if omitted."}
    },
    "examples": {
      "creative_self": "gamemode creative",
      "survival_player": "gamemode survival slingshooter08",
      "spectator_all": "gamemode spectator @a"
    },
    "version_notes": "No significant changes in 1.21. Numeric IDs (0,1,2,3) and abbreviations (s,c,a,sp) are NOT valid in JE.",
    "common_errors": [
      "'gameMode' (camelCase) is not a valid command -- use lowercase 'gamemode'",
      "Abbreviations 's', 'c', 'a', 'sp' are NOT valid in JE -- use full words",
      "Numeric modes '0', '1', '2', '3' are NOT valid in JE -- use full words"
    ]
  },
  {
    "command": "fill",
    "description": "Fills a region with a specified block",
    "je_syntax": ["fill <from> <to> <block> [destroy|hollow|keep|outline|replace [<filter>]]"],
    "arguments": {
      "from": {"type": "block_pos", "description": "One corner of the fill region (X Y Z integers or ~ notation)."},
      "to": {"type": "block_pos", "description": "Opposite corner of the fill region."},
      "block": {"type": "block_state", "description": "Block to fill with, including optional states: minecraft:stone, minecraft:oak_stairs[facing=north]."},
      "mode": {"type": "literal", "description": "destroy (drops items), hollow (fills edges only, air inside), keep (only replaces air), outline (fills edges only, interior unchanged), replace (default, replaces all blocks)."},
      "filter": {"type": "block_predicate", "description": "When using 'replace', only replace blocks matching this filter."}
    },
    "examples": {
      "basic_fill": "fill 0 64 0 10 68 10 minecraft:stone",
      "replace_air": "fill -10 60 -10 10 70 10 minecraft:glass replace air",
      "hollow_box": "fill 0 64 0 10 74 10 minecraft:stone hollow",
      "clear_area": "fill -20 60 -20 20 80 20 minecraft:air",
      "fire_replace_air": "fill -25 64 -25 25 68 25 minecraft:fire replace air"
    },
    "version_notes": "1.21: No block metadata numbers. 'fill ... fire 0 replace air' is invalid. Use 'fill ... minecraft:fire replace air'.",
    "common_errors": [
      "Using metadata numbers: 'fill ... fire 0' is invalid in 1.21. Drop the '0'.",
      "Max fill volume is 32768 blocks per command",
      "Missing minecraft: prefix on block ID"
    ]
  },
  {
    "command": "setblock",
    "description": "Places a block at a position",
    "je_syntax": ["setblock <pos> <block> [destroy|keep|replace]"],
    "arguments": {
      "pos": {"type": "block_pos", "description": "X Y Z position for the block."},
      "block": {"type": "block_state", "description": "Block to place with optional states: minecraft:oak_door[facing=north,half=upper]."},
      "mode": {"type": "literal", "description": "destroy (drops old block as item), keep (only place if current block is air), replace (default)."}
    },
    "examples": {
      "basic": "setblock 0 64 0 minecraft:diamond_block",
      "with_state": "setblock 0 64 0 minecraft:oak_door[facing=north,half=lower]",
      "keep": "setblock 0 64 0 minecraft:torch keep"
    },
    "version_notes": "No significant changes in 1.21.",
    "common_errors": ["Missing minecraft: prefix on block ID"]
  },
  {
    "command": "clone",
    "description": "Copies blocks from one region to another",
    "je_syntax": [
      "clone [from <sourceDimension>] <begin> <end> [to <targetDimension>] <destination> [replace|masked] [force|move|normal]",
      "clone [from <sourceDimension>] <begin> <end> [to <targetDimension>] <destination> filtered <filter> [force|move|normal]"
    ],
    "arguments": {
      "begin": {"type": "block_pos", "description": "One corner of source region."},
      "end": {"type": "block_pos", "description": "Opposite corner of source region."},
      "destination": {"type": "block_pos", "description": "Lower northwest corner of destination region."},
      "maskMode": {"type": "literal", "description": "replace (all blocks), masked (skip air blocks), filtered (only matching blocks)."},
      "cloneMode": {"type": "literal", "description": "force (allows overlap), move (fills source with air), normal (default, no overlap allowed)."}
    },
    "examples": {
      "basic": "clone 0 64 0 10 74 10 100 64 100",
      "masked": "clone 0 64 0 10 74 10 100 64 100 masked",
      "move": "clone 0 64 0 10 74 10 100 64 100 replace move"
    },
    "version_notes": "1.20.2+: Added cross-dimension cloning with 'from' and 'to' dimension arguments.",
    "common_errors": ["Cloning to overlapping region without 'force' mode", "No-op clone (source equals destination)"]
  },
  {
    "command": "summon",
    "description": "Summons an entity",
    "je_syntax": ["summon <entity> [<pos>] [<nbt>]"],
    "arguments": {
      "entity": {"type": "resource", "description": "Entity type ID: minecraft:zombie, minecraft:tnt, etc."},
      "pos": {"type": "vec3", "description": "Position to summon at. Defaults to executor position."},
      "nbt": {"type": "compound_tag", "description": "NBT data for the entity (still uses NBT, not data components)."}
    },
    "examples": {
      "basic": "summon minecraft:zombie ~ ~ ~",
      "at_coords": "summon minecraft:tnt 0 65 0",
      "with_nbt": "summon minecraft:zombie ~ ~ ~ {IsBaby:1}",
      "named": "summon minecraft:villager ~ ~ ~ {CustomName:'\"Bob\"'}"
    },
    "version_notes": "summon still uses NBT tags (not data components) as of 1.21. Cannot append count to summon -- each call creates exactly one entity.",
    "common_errors": [
      "'summon tnt ~ ~1 ~ 20' is INVALID -- cannot append count. Must use separate summon commands for multiple entities.",
      "Missing minecraft: namespace prefix on entity type"
    ]
  },
  {
    "command": "worldborder",
    "description": "Manages the world border",
    "je_syntax": [
      "worldborder add <distance> [<time>]",
      "worldborder center <pos>",
      "worldborder damage amount <damagePerBlock>",
      "worldborder damage buffer <distance>",
      "worldborder get",
      "worldborder set <distance> [<time>]",
      "worldborder warning distance <distance>",
      "worldborder warning time <time>"
    ],
    "arguments": {
      "distance": {"type": "float/int", "description": "Border diameter in blocks. For 'add', positive expands, negative shrinks."},
      "time": {"type": "integer", "description": "Seconds for the border to reach its target size. 0 = instant."},
      "pos": {"type": "vec2", "description": "X Z center coordinates."}
    },
    "examples": {
      "get_size": "worldborder get",
      "set_500": "worldborder set 500",
      "shrink_over_time": "worldborder set 100 600",
      "center": "worldborder center 0 0"
    },
    "version_notes": "No significant changes in 1.21.",
    "common_errors": ["'worldborder set 0' sets border to zero, effectively killing all players outside center"]
  },
  {
    "command": "enchant",
    "description": "Enchants the held item of a player",
    "je_syntax": ["enchant <targets> <enchantment> [<level>]"],
    "arguments": {
      "targets": {"type": "entity", "description": "Player(s) whose held item to enchant."},
      "enchantment": {"type": "resource", "description": "Enchantment ID: minecraft:sharpness, minecraft:protection, etc."},
      "level": {"type": "integer", "description": "Enchantment level. Defaults to 1. Cannot exceed max vanilla level."}
    },
    "examples": {
      "basic": "enchant @s minecraft:sharpness 5",
      "all_players": "enchant @a minecraft:unbreaking 3"
    },
    "version_notes": "The /enchant command only works on the item the player is currently holding. It respects vanilla max levels and compatibility rules. For pre-enchanted items, use /give with component syntax instead: give @s diamond_sword[enchantments={sharpness:5}]",
    "common_errors": [
      "Using /enchant to fully enchant items is unreliable -- it only affects held item and respects vanilla limits. Prefer /give with enchantment components for guaranteed results.",
      "Cannot stack incompatible enchantments (e.g. sharpness + smite)"
    ]
  },
  {
    "command": "scoreboard",
    "description": "Manages scoreboard objectives and player scores",
    "je_syntax": [
      "scoreboard objectives add <objective> <criteria> [<displayName>]",
      "scoreboard objectives list",
      "scoreboard objectives modify <objective> displayname <displayName>",
      "scoreboard objectives modify <objective> rendertype (hearts|integer)",
      "scoreboard objectives remove <objective>",
      "scoreboard objectives setdisplay <slot> [<objective>]",
      "scoreboard players add <targets> <objective> <score>",
      "scoreboard players display name <targets> <objective> <name>",
      "scoreboard players display numberformat <targets> <objective> ...",
      "scoreboard players enable <targets> <objective>",
      "scoreboard players get <target> <objective>",
      "scoreboard players list [<target>]",
      "scoreboard players operation <targets> <targetObjective> <operation> <source> <sourceObjective>",
      "scoreboard players remove <targets> <objective> <score>",
      "scoreboard players reset <targets> [<objective>]",
      "scoreboard players set <targets> <objective> <score>"
    ],
    "examples": {
      "create_objective": "scoreboard objectives add deaths deathCount \"Deaths\"",
      "set_score": "scoreboard players set @s deaths 0",
      "add_score": "scoreboard players add @s deaths 1",
      "display": "scoreboard objectives setdisplay sidebar deaths"
    },
    "version_notes": "No significant changes in 1.21.",
    "common_errors": []
  },
  {
    "command": "data",
    "description": "Gets, merges, modifies, or removes NBT data from entities, block entities, or storage",
    "je_syntax": [
      "data get (block <targetPos>|entity <target>|storage <target>) [<path>] [<scale>]",
      "data merge (block <targetPos>|entity <target>|storage <target>) <nbt>",
      "data modify (block <targetPos>|entity <target>|storage <target>) <targetPath> (append|insert <index>|merge|prepend|set) (from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]|string (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>] [<start>] [<end>]|value <value>)",
      "data remove (block <targetPos>|entity <target>|storage <target>) <path>"
    ],
    "examples": {
      "get_player_pos": "data get entity slingshooter08 Pos",
      "get_block_data": "data get block 0 64 0",
      "get_health": "data get entity @p Health",
      "get_inventory": "data get entity @p Inventory"
    },
    "version_notes": "'data get block' only works on block entities (chests, signs, etc.), NOT regular blocks like stone or grass.",
    "common_errors": [
      "'data get block' on non-block-entity blocks returns 'The target block is not a block entity'",
      "Cannot modify player data directly with 'data merge entity' in most cases"
    ]
  }
]