StarEnchants

Use when running or verifying StarEnchants' test gate — which commands to run, the Paper+Folia version matrix, concurrency rules for booting many servers, and how to read results honestly instead of trusting a success banner.

Use when implementing or modifying the runtime engine — stateless systems, the activation pipeline and gate order, effect/condition/trigger/selector kinds, the Ability record, the Sink, declared Affinity, the dispatch plan, or how one activation executes.

Use when working on item state, the PDC codec, the ItemView content-hash cache, the stable-key to dense-id map, component stores, the WornState resolver, lore/name rendering, or legacy item migration.

Use when writing or reviewing ANY code in the StarEnchants repo — the design principles, engine boundaries, threading/Folia rules, config snapshot pattern, extensibility pattern, and the invariants every change must preserve.

Use when writing or reviewing code on the combat or item hot path, declaring an effect Affinity, touching the Sink/Dispatcher, the ItemView cache, interning, or anything the ArchUnit/CI lint or the JMH bench guards.

Use when working on the config schema/YAML, the DSL and ParamSpec, the compiler (resolve/typecheck/lower/erase/snapshot), diagnostics, transactional reload, catalog validation, or the EE/EA/AE and legacy-config migrator.

Use when touching the 1.8.9 legacy overlay, -Pse.target=legacy builds, JvmDowngrader, the mega-jar, or the legacy/mega smoke gates.

Use when writing, reviewing, removing, or restructuring ANY test in StarEnchants — deciding whether a test should exist, which layer it belongs in, and how to write it so it catches real bugs without breaking on non-bugs. Supersedes the unit-vs-live notes in live-server-testing / matrix-gate.

Use when two or more features interact — damage/reduction stacking, DISABLE_ENCHANT/GROUP/TYPE suppression, souls, slots, crystal stacking, omni/multi-set completion, or custom-enchant stamping onto gear.

Use when writing or changing code that must run across StarEnchants' whole Paper range (1.17.1 → 26.1.x) — API selection, version-gated features, reflection, the 1.20.5 mapping flip, enum→registry breaks, or Java toolchains.

Use when you need authoritative Paper or Folia API/behavior for a specific Minecraft version — points to the local cache of per-version server jars (for javap) and the cached Paper/Folia developer docs, instead of guessing or going to the network.

Use when writing or reviewing comments or Javadoc in any source file — deciding what to comment, trimming verbose/redundant comments, or removing development-history narration. Applies to all code in the repo.

Use when any StarEnchants code touches entities, blocks, worlds, inventories, or timers and must run on BOTH Paper and Folia — covers Folia's region/entity/global thread model and the scheduling abstraction that makes one codebase correct on both.

Use when writing or debugging StarEnchants integration tests that boot real Paper or Folia servers, or when a live suite is flaky, hangs, or passes on Paper but fails on Folia.

Use when server internals behave unexpectedly on a specific Minecraft version — a reflection lookup misses, a field seems renamed or relocated, a mechanic gates differently. Gives the javap-based procedure for reading the actual server instead of guessing.

Use when referencing any Bukkit Material, Sound, Particle, Enchantment, PotionEffectType, Attribute, EntityType, or ItemMeta/PDC API that StarEnchants must resolve across 1.17.1 → 26.1.x — the enum→registry renames, legacy aliases in user configs, and the boot-time resolver pattern that absorbs them.