Rewrite admin docs (challenges.md + customization.md) for the new immutable catalog schema

[minoneer]

Summary: The admin docs (docs/src/admin/challenges.md and the biome section of docs/src/admin/customization.md) describe only the legacy challenge format, but the shipped 4.0 engine parses a new schemaVersion: 1 catalog and the first-boot importer rewrites challenges.yml into it. Any admin who opens the file after first run sees a schema the docs do not describe, so the docs are effectively wrong for the shipped engine.

Why this blocks 4.0

The catalog parser hard-requires a root schemaVersion key and rejects any file without it (ChallengeCatalogYamlParser.java:70-71: Missing required root key '$.schemaVersion'), while the first-boot importer destructively rewrites the admin's challenges.yml into that schema (LegacyChallengeCatalogImporter.java:58,113). The current challenges.md documents the opposite format (allowChallenges, requiredItems/requiredBlocks/requiredEntities, type: onPlayer/onIsland/islandLevel) and never mentions schemaVersion or any of the new requirement types. An admin following the docs after upgrading edits keys that no longer exist and gets a parse failure they cannot diagnose from the documentation. This is a shipping blocker because admin customization is a primary supported workflow and the docs actively mislead.

Current state

• docs/src/admin/challenges.md documents the legacy schema only: top-level allowChallenges, per-challenge type: onPlayer | onIsland | islandLevel, requiredItems, requiredBlocks, requiredEntities, requiredLevel, requiredChallenges, and rank-level requires:. A grep of that file for schemaVersion, inventory-items, island-blocks, entity-presence, completed-rank, any-of, and #tag returns nothing.
• The shipped engine parses a new schema (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/yaml/ChallengeCatalogYamlParser.java):
  • Requires root schemaVersion; rejects its absence (line 70-71) and any unsupported version (line 73-74).
  • Requirement types are completed-challenges, completed-rank, permission, island-level, inventory-items, island-blocks, entity-presence (dispatch at lines 372-395). None of these names appear in the docs.
  • completed-rank gating takes rank + minimumCompletedChallenges (lines 378-385).
  • Block and item matchers accept a plain material, a #-prefixed data-pack tag (e.g. #minecraft:beds), or an any-of YAML list (ChallengeRequirements.java:92,172).
• The first-boot importer (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/bootstrap/LegacyChallengeCatalogImporter.java):
  • Treats a file as legacy when it has no schemaVersion (line 58).
  • Backs up the legacy file, then atomically rewrites challenges.yml with schemaVersion = TARGET_SCHEMA_VERSION (line 113), emitting completed-rank unlock rules and inventory-items / island-blocks / entity-presence completion steps (lines 156, 272, 301, 309). Confirmed by ChallengeCatalogBootstrapTest asserting schemaVersion == 1 after import.
• Biome rewards now exist and are undocumented. ChallengeRewards.BiomeReward (ChallengeRewards.java:38) is parsed from a reward type: biome (ChallengeCatalogYamlParser.java:271), and IslandBiomeUnlocks derives an island's biome access from its completed challenges' biome rewards, treating the personal usb.biome.<key> permission only as an OR-fallback (class javadoc, IslandBiomeUnlocks.java:25-27).
• docs/src/admin/customization.md:58 still states "Access is still controlled by permissions. Grant usb.biome.<name> ... or usb.biome.*" with no mention of biome-reward unlocks, so the biome-access description is now incomplete.

Scope

• Rewrite docs/src/admin/challenges.md to document the schemaVersion: 1 catalog as the canonical format (replace, not append to, the legacy field tables).
• Document each requirement type: inventory-items, island-blocks, entity-presence, completed-challenges, completed-rank (with rank + minimumCompletedChallenges), permission, and island-level.
• Document material/block/item matcher forms: plain material, #-prefixed data-pack tags, and any-of lists.
• Document the reward type: biome action and how island biome unlocks are derived from completed-challenge biome rewards (retroactive; reset on island create/restart), per IslandBiomeUnlocks.
• Update docs/src/admin/customization.md biome section (around line 58) to explain that biome access comes from completed-challenge biome rewards with usb.biome.<key> / usb.biome.* as an OR-fallback, rather than "controlled by permissions" alone.
• Document the first-boot importer behavior: a legacy challenges.yml (no schemaVersion) is backed up and rewritten in place to schemaVersion: 1, so admins should expect the on-disk schema to change after first run.
• State that editing challenges.yml without a schemaVersion root key now fails to load, and explain the failure message admins will see.
• Verify every example in the rewritten docs parses against the shipped parser (cross-check field names against ChallengeCatalogYamlParser).

References

• Related: Island-scoped biome unlocking as a first-class challenge reward (4.0) #145 (biome rewards) — the biome-access doc change here depends on that feature; Localize default challenge text from challenges.yml #114 (challenge text i18n) is a separate track, not duplicated here.
• Design draft: docs/challenge-redesign/uskyblock-v2-challenge-redesign.md (currently untracked / do-not-commit) — source of truth for schema intent.
• Key files: docs/src/admin/challenges.md, docs/src/admin/customization.md, uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/yaml/ChallengeCatalogYamlParser.java, uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/bootstrap/LegacyChallengeCatalogImporter.java, uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/ChallengeRewards.java, uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/IslandBiomeUnlocks.java.

Category: docs · Effort: medium · Source: 4.0 readiness survey.