Document sealed artifact crafting and recycling

projects/Dowsing/overview.md

@@ -17,7 +17,8 @@ upkeep calculations.
 
 ## Configuration files
 
-The plugin copies its defaults into `plugins/Dowsing/` on first start.
+The plugin copies each missing configuration file into `plugins/Dowsing/` from
+the jar. Updating the jar does not overwrite existing files.
 
 | File | Purpose |
 | --- | --- |
@@ -31,6 +32,11 @@ Cross-file identifiers must resolve in this order: block definitions reference
 types, types reference slots, and slots reference production methods. Item paths
 use the prefixes understood by TLibs and the installed item providers.
 
+The magical mine's `artifact_focus` is displayed as Artifact Mine. It requires
+diamond tools and uses Magic artifact paths for its drops. The focus ID remains
+`artifact_focus` for existing node selections. Compare existing configuration
+files explicitly when adopting updated defaults.
+
 Run `/dowsing reload` after editing these files. Reloading temporarily caches
 the live nodes, reloads all definitions, restores the cached state, and
 recalculates faction node benefits.

projects/Magic/docs/SYSTEM.md

@@ -11,6 +11,7 @@ All paths under `plugins/Magic/` on the server.
 | `config.yml` | `debug`, `default_cast_mode`, equilibrium rates, tick interval |
 | `gui.yml` | Title, slot map, filler icons, cast mode definitions, bar templates, hex color tokens |
 | `messages.yml` | Player-facing chat strings |
+| `artifacts/sealed.yml` | Sealed-item paths, school selection, rarity weights and opening sound |
 | `elements/*.yml` | Element catalog (name, icon, color, skills) |
 | `data/characters/<characterId>.json` | Per-character MagicProfile (cast mode, equilibrium, resonance) |
 
@@ -130,6 +131,45 @@ low part of Epic's old cap range and Legendary the high part (planar schools
 moved to Legendary and its models became Legendary-only. Existing Epic
 artifacts keep working; their lore shows the raw id `epic`.
 
+## Sealed artifact crafting
+
+Magic 0.11.0 supports sealed artifacts crafted at the MMOItems Rune Crafting
+Station. The station recipes and sealed LOOT items are supplied by ServerAssets;
+Magic handles opening them.
+
+| Recipe | Enchanted Dust | Result when opened |
+| --- | --- | --- |
+| Sealed Artifact | 18 | A random planar-school artifact |
+| Sealed Oseni Artifact | 28 | An Oseni artifact |
+| Sealed Seithr Artifact | 28 | A Seithr artifact |
+| Sealed Cerrith Artifact | 28 | A Cerrith artifact |
+| Sealed Mitlan Artifact | 28 | A Mitlan artifact |
+
+Hold the sealed item in the main hand and right-click to open it. A normal
+right-click on an interactive block, such as a chest, uses that block instead;
+sneak-right-click opens the seal. The server's off-hand equipment rules can
+prevent holding a seal in that hand.
+
+Each successful opening consumes one sealed item and gives one empty artifact.
+If the inventory cannot hold the result, it drops at the player's feet. A failed
+roll leaves the seal intact. School-specific crafts retain the normal chance of
+secondary schools; choosing a school fixes the primary school only. Opened
+artifacts use the same aura, care, meditation wear, husks and
+[rarity-based recycling](../../Recycler/docs/SYSTEM.md#magic-artifacts) as node
+artifacts. They still need charging before meditation.
+
+`artifacts/sealed.yml` is created from the jar when missing and is loaded again
+by `/magic reload`. The `sealed` entries map TLibs `item` paths to an `element`
+selection. `random` selects from the generator's configured random pool; an
+entry may override the shared rarity weights. Invalid entries are skipped with
+warnings, and an unreadable file disables seal opening. Existing files are not
+overwritten. The supplied item paths are `m.loot.sealed_artifact` and
+`m.loot.sealed_<school>_artifact` for the four named recipes above.
+
+Successful openings are recorded in the server log as `Sealed artifact opened`,
+including player, seal, school, rarity and artifact ID. They are not recorded in
+`aura.log`.
+
 ## Persistence (MagicProfile)
 
 Profiles are keyed by the character UUID from the

projects/Magic/docs/TEST_MATRIX.md

@@ -105,6 +105,25 @@ Run these checks on Minecraft **1.21.10** with the intended plugin dependencies
 - [ ] Bump a part revision and `/magic reload`: a skinned weapon refreshes and keeps its skin; an unskinned one takes the part model
 - [ ] A weapon whose skin was lost before this fix keeps the part model after a refresh
 
+## Sealed artifacts
+
+Use the [sealed artifact setup](SYSTEM.md#sealed-artifact-crafting) with MMOItems
+and the matching ServerAssets items and station recipes.
+
+- [ ] Startup loads all five sealed definitions; a missing `artifacts/sealed.yml` is created without overwriting an existing copy
+- [ ] Rune Crafting Station offers the random recipe at 18 dust and each named-school recipe at 28; crafting consumes the listed dust and claiming gives the matching sealed LOOT item
+- [ ] Main-hand right-click opens one seal into one empty artifact; repeated events for the same click do not open another seal
+- [ ] Two players opening seals in the same tick each consume only their own single seal
+- [ ] Each named-school seal fixes its primary school and still permits normal secondary schools
+- [ ] Random seals use the configured random pool and rarity weights
+- [ ] An ordinary right-click on a chest opens it without consuming the seal; sneak-right-click opens the seal
+- [ ] If the result cannot fit after consuming the seal, it drops at the player's feet
+- [ ] A failed artifact roll consumes nothing; ordinary items do not trigger seal opening
+- [ ] `/magic reload` picks up sealed-definition edits and warns about invalid entries without breaking other artifact configs
+- [ ] Successful openings write `Sealed artifact opened` to the server log
+- [ ] Opened artifacts charge, meditate, wear into husks and recycle through the usual artifact rules; shipped Recycler recipes refuse unopened seals
+- [ ] Check the server's off-hand equipment restrictions separately; they may return a seal to inventory before Magic can open it
+
 ## Artifact generator
 
 ### Server setup

projects/Recycler/docs/SYSTEM.md

@@ -108,8 +108,11 @@ Magic 0.4.7+ stamps the materials a craft actually charged on the weapon (`magic
 ### Magic (artifacts)
 
 `ArtifactProvider` returns the configured item by the artifact's recorded
-rarity. Artifacts are found rather than crafted, so they do not need a crafting
-record. Stored aura is lost.
+rarity. Node artifacts and artifacts opened from
+[crafted sealed items](../../Magic/docs/SYSTEM.md#sealed-artifact-crafting) use
+the same rarity table rather than a crafting record. Recycling does not refund
+the seal's crafting cost. Stored aura is lost. Unopened seals are not artifacts,
+and the shipped recycling recipes do not accept them.
 
 ```yaml
 artifact_returns:
@@ -140,8 +143,9 @@ aura, so `min_muffle` does not apply to them. They return `husk_fraction`
 returns 14. A husk worth 0 is refused before recipe fallback, like an artifact.
 
 `return_rates.artifacts` multiplies these amounts using the normal return math.
-The shipped rarity table is tuned so recycling the artifacts from a Dowsing
-Artifact Mine node yields roughly half the enchanted dust of a Dust Mine node.
+Average returns depend on the source's rarity weights and the configured return
+rates; node production also depends on its level, efficiency and production
+methods. A fixed Artifact Mine-to-Dust Mine yield ratio is not guaranteed.
 
 ### GunsAndGadgets (guns)