From 888095890b026fceece3298f2fc052a332eb9e30 Mon Sep 17 00:00:00 2001
From: Mathih13 <mhartveit61@gmail.com>
Date: Sat, 10 Oct 2026 14:33:59 +0200
Subject: [PATCH 1/5] feat(packages): move the Reference Packages to the
 collection

---
 .gitignore                                    |  12 +-
 .lyracore-cli-rev                             |   2 +-
 CONTEXT.md                                    |  14 +-
 CONTRIBUTING.md                               |   2 +-
 .../lyracore-test-support/src/module_wasm.rs  |   2 +-
 datascripts/tests/emit.test.ts                |   4 +-
 .../tests/fixtures/fire-nova.expected.json    |   2 +-
 .../spells.ts => tests/fixtures/fire_nova.ts} |  19 +--
 docs/development-cli.md                       |  61 ++++----
 docs/package-api.md                           |   2 +-
 docs/schema.md                                |   2 +-
 module/Cargo.toml                             |   2 +
 module/build.rs                               |  44 +++---
 module/src/actor.rs                           |   8 +-
 module/src/group.rs                           |   5 +-
 module/src/lib.rs                             |   5 +-
 module/src/test_scan.rs                       |   8 +-
 module/tests/fixtures/test_fixture.rs         |   1 +
 module/tests/package_account.rs               |   8 +-
 module/tests/package_runtime_scripts.rs       |  61 ++++----
 module/tests/package_teardown.rs              |   4 +-
 packages/README.md                            | 130 +++++++++---------
 packages/example/src/mod.rs                   |  23 ----
 packages/fire_nova/README.md                  |  23 ----
 packages/fire_nova/data/.gitkeep              |   0
 packages/fire_nova/scripts/ember_echo.ts      |  25 ----
 26 files changed, 189 insertions(+), 280 deletions(-)
 rename datascripts/{src/fire_nova/spells.ts => tests/fixtures/fire_nova.ts} (70%)
 create mode 100644 module/tests/fixtures/test_fixture.rs
 delete mode 100644 packages/example/src/mod.rs
 delete mode 100644 packages/fire_nova/README.md
 delete mode 100644 packages/fire_nova/data/.gitkeep
 delete mode 100644 packages/fire_nova/scripts/ember_echo.ts

diff --git a/.gitignore b/.gitignore
index b5a77ab6b..0500ffdef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,15 +55,9 @@ __pycache__/
 /datascripts/node_modules/
 /datascripts/runtime-scripts/node_modules/
 
-# Packages installed on a host (`lyracore packages add`) are local to that checkout. Unknown
-# Package directories stay out of Git status. Source files in the committed first-party Packages
-# remain visible.
+# Installed Packages are local to this checkout. Reference Packages live in the collection.
 /packages/*
-!/packages/example/
-!/packages/fire_nova/
+!/packages/README.md
 
-# What `lyracore packages build` writes into a first-party Package: Package Deltas, Script Artifacts
-# and their Build Identity sidecars. Here they are output the sources next to them reproduce, so
-# none is committed. A Package Delta is never committed anywhere (licensing firewall); the Official
-# Package Collection does commit Script Artifacts, so an Operator installs prebuilt Lua without Bun.
+# Generated Package output stays local. The collection may commit Script Artifacts, never Deltas.
 /packages/*/data/.generated/
diff --git a/.lyracore-cli-rev b/.lyracore-cli-rev
index 5c13cdf7a..094bc10d5 100644
--- a/.lyracore-cli-rev
+++ b/.lyracore-cli-rev
@@ -1 +1 @@
-091b502a1020e483df4322881bd808e0e6c958db
+950a03ff593722109482ab6dd496e94148ecf709
diff --git a/CONTEXT.md b/CONTEXT.md
index 5032a3fe2..d7c38ebf5 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -961,15 +961,15 @@ rows, so the Package's tables must be empty first. `lyracore packages disable` r
 _Avoid_: uninstall, package wipe, cleanup
 
 **Reference Package**:
-The maintained, minimal Package at `packages/example/`, committed to the LyraCore repo and present in every checkout. It doubles as living documentation for a Package's shape and is the template `lyracore packages new` copies and renames. It is deliberately inert: Rust-only, one commented hook pattern, no gameplay behavior.
+One rung of the maintained example ladder in the [Official Package Collection](https://github.com/LyraCoreProject/packages#packages): `example-script`, `example-client`, `example-data`, `example-rust` or `example-all`. Each adds a small welcome at one level of the Package API. `lyracore packages new NAME [--from RUNG]` copies and renames one at the collection tag matching the checkout's Package API version. The default is `example-script`. Core ships no enabled Reference Package.
 _Avoid_: template package, sample package
 
 **Package Source**:
-Where an installed Package was copied from: a local folder on the Operator's machine, a Git Package Source, or an Official Package Source. A scaffolded Package (`lyracore packages new`) has none. It was not copied from anywhere the Operator chose, so its Provenance Stamp records a scaffold origin instead.
+Where an installed Package was copied from: a local folder on the Operator's machine, a Git Package Source, or an Official Package Source. A scaffolded Package records a scaffold origin, its Reference Package rung and the collection revision. The author owns that copy; `packages update` does not replace it.
 _Avoid_: origin, upstream, repo
 
 **Git Package Source**:
-A repository whose root is one Package, named by a URL. `lyracore packages add <git-url>` clones it and installs a copy of its tree, without the `.git`. An installed Package is never a working copy, so `lyracore packages update` re-clones rather than pulling. A Package installed this way is Git-backed, and it is the only kind `update` can advance.
+A repository whose root is one Package, named by a URL. `lyracore packages add <git-url>` clones it and installs a copy of its tree, without the `.git`. An installed Package is never a working copy, so `lyracore packages update` re-clones rather than pulling. A Package installed this way is Git-backed, and `packages update` can advance it.
 _Avoid_: git remote, upstream repo, checkout
 
 **Official Package Collection**:
@@ -977,15 +977,15 @@ The one repository, `LyraCoreProject/packages`, that holds several first-party P
 _Avoid_: registry, package repository, marketplace
 
 **Official Package Source**:
-The top-level directory of the Official Package Collection that a bare `lyracore packages add <name>` installed. Its Provenance Stamp records the collection's URL and the Recorded Revision the directory was resolved at, the same way a Git Package Source records its repository and commit. The commit is pinned at install time: `lyracore packages update` refuses this kind by name, so a later commit to the collection cannot silently change what is installed.
+The top-level directory of the Official Package Collection that a bare `lyracore packages add <name>` installed. Its Provenance Stamp records the collection's URL and the Recorded Revision the directory was resolved at, the same way a Git Package Source records its repository and commit. The checkout's Package API version selects a collection tag. `packages update` resolves that tag again and records the new commit after the update passes its checks.
 _Avoid_: registry entry, published package
 
 **Recorded Revision**:
-The exact commit a Git Package Source or an Official Package Source was installed at, held in its Provenance Stamp. `lyracore packages update` advances a Git Package Source from this rather than from whatever the repository's branch points at now, so it can name both commits when it reports or restores.
+The exact commit a Git Package Source, Official Package Source or Reference Package was copied from, held in its Provenance Stamp. `lyracore packages update` advances a Git Package Source from this rather than from whatever the repository's branch points at now, so it can name both commits when it reports or restores.
 _Avoid_: version, tag, pin
 
 **Provenance Stamp**:
-The record `lyracore packages add` writes inside an installed Package: its Package Source, its Content Identity at install time, when it was installed, and, for a Git or Official Package Source, its Recorded Revision. A Package without one is still a Package; only its history is unknown.
+The record `lyracore packages add` writes inside an installed Package: its Package Source, its Content Identity at install time, when it was installed, and, for a Git or Official Package Source or a scaffold, its Recorded Revision. A scaffold also records its Reference Package rung. A Package without one is still a Package; only its history is unknown.
 _Avoid_: manifest, lockfile, metadata
 
 **Content Identity**:
@@ -1005,7 +1005,7 @@ The maintained, minimal Datascript at `datascripts/src/reference.ts`. It names r
 _Avoid_: sample script, test script
 
 **Authoring Library**:
-The typed API at `datascripts/lib/` that a Datascript writes against: `data.spell(id)`, `.clone(newId)`, `.set(field, value)`, `.effect(0 | 1 | 2)`, and a `run(package, script)` that emits one Package Delta. It reads the Base Snapshot and refuses exactly what the artifact parser refuses, so a Datascript fails at author time rather than at import. Its source lives outside the Package folder; only the generated artifact goes inside.
+The typed API at `datascripts/lib/` that a Datascript writes against: `data.spell(id)`, `.clone(newId)`, `.set(field, value)`, `.effect(0 | 1 | 2)`, and a `run(package, script)` that emits one Package Delta. It reads the Base Snapshot and refuses exactly what the artifact parser refuses, so a Datascript fails at author time rather than at import. The library lives in Core. A Package carries its Datascripts in `datascripts/`; Core's legacy `datascripts/src/<package>/` path also works.
 _Avoid_: SDK, framework, DSL, builder API
 
 **Base Snapshot**:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c1fabde0c..31d8848c6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,7 +42,7 @@ first commit. A maintainer then marks the issue `in progress`.
 ## Building on top
 
 New content and behaviour beyond 1.12.1 live in a Package. `lyracore packages new <name>`
-scaffolds one from the reference Package. [`docs/package-api.md`](docs/package-api.md) lists what
+scaffolds one from the Reference Package ladder in the collection. Use `--from` to choose a rung. [`docs/package-api.md`](docs/package-api.md) lists what
 a Package may call, and the build fails on anything else. The Official Package Collection,
 [LyraCoreProject/packages](https://github.com/LyraCoreProject/packages), takes pull requests under
 its own contributing guide.
diff --git a/crates/lyracore-test-support/src/module_wasm.rs b/crates/lyracore-test-support/src/module_wasm.rs
index 58f16eda5..68a5196a7 100644
--- a/crates/lyracore-test-support/src/module_wasm.rs
+++ b/crates/lyracore-test-support/src/module_wasm.rs
@@ -17,7 +17,7 @@ fn build_module_bytes() -> Vec<u8> {
             "--release",
             "--target",
             "wasm32-unknown-unknown",
-            "--features=debug_reducers",
+            "--features=debug_reducers,package_test_fixture",
         ],
     );
     let bytes = std::fs::read(&wasm).expect("the test Module output is missing");
diff --git a/datascripts/tests/emit.test.ts b/datascripts/tests/emit.test.ts
index 18b1fd210..9477498b3 100644
--- a/datascripts/tests/emit.test.ts
+++ b/datascripts/tests/emit.test.ts
@@ -7,7 +7,7 @@
 //
 //   LYRACORE_BASE_SNAPSHOT=datascripts/tests/fixtures/base-snapshot.json \
 //   LYRACORE_PACKAGES_ROOT=<scratch dir> \
-//   bun run datascripts/src/fire_nova/spells.ts
+//   bun run datascripts/tests/fixtures/fire_nova.ts
 //
 // The Datascript is run as a SUBPROCESS rather than imported, because the source hash it records is
 // the entry script's own digest — which only means what it says when the entry script is the
@@ -19,7 +19,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const REPO = join(import.meta.dir, "..", "..");
-const DATASCRIPT = join(REPO, "datascripts", "src", "fire_nova", "spells.ts");
+const DATASCRIPT = join(import.meta.dir, "fixtures", "fire_nova.ts");
 const SNAPSHOT = join(import.meta.dir, "fixtures", "base-snapshot.json");
 const FROZEN = join(import.meta.dir, "fixtures", "fire-nova.expected.json");
 
diff --git a/datascripts/tests/fixtures/fire-nova.expected.json b/datascripts/tests/fixtures/fire-nova.expected.json
index 72a86e879..d13f8bf09 100644
--- a/datascripts/tests/fixtures/fire-nova.expected.json
+++ b/datascripts/tests/fixtures/fire-nova.expected.json
@@ -1 +1 @@
-{"version":1,"package":"fire_nova","source_hash":"f3dd07e4c214bbe5384623b1b0be7674c6cea25ae986c639d76ff64bd98df64d","claims":[{"table":"game_spell","key":{"spell_id":6000100},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":40},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 1)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":12},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000101},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":80},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 2)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":22},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000102},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":145},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 3)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":32},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000103},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":240},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 4)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":42},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000104},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":355},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 5)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":52},"stances":{"type":"u8","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000100,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":33},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000100,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000101,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":71},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000101,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000102,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":129},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000102,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000103,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":224},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000103,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000104,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":340},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000104,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}}]}
\ No newline at end of file
+{"version":1,"package":"fire_nova","source_hash":"e84139afd0f845c0c590983687564f8116889e7151fc1a52616192e11c806bd5","claims":[{"table":"game_spell","key":{"spell_id":6000100},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":40},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 1)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":12},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000101},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":80},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 2)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":22},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000102},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":145},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 3)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":32},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000103},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":240},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 4)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":42},"stances":{"type":"u8","value":0}}},{"table":"game_spell","key":{"spell_id":6000104},"operation":"insert","fields":{"attributes":{"type":"u32","value":0},"aura_interrupt":{"type":"u16","value":1},"cast_flags":{"type":"u32","value":0},"cast_time_ms":{"type":"u32","value":0},"cooldown_ms":{"type":"u32","value":8000},"cost":{"type":"u32","value":355},"dispel_type":{"type":"u8","value":1},"duration_ms":{"type":"u32","value":6000},"family_flags":{"type":"u64","value":"1024"},"family_name":{"type":"u8","value":3},"gcd_ms":{"type":"u32","value":1500},"is_negative":{"type":"bool","value":true},"max_level":{"type":"u8","value":0},"max_stacks":{"type":"u8","value":0},"mechanic":{"type":"u8","value":0},"name":{"type":"string","value":"Fire Nova (Rank 5)"},"power_type":{"type":"u8","value":0},"proc_chance":{"type":"u8","value":0},"proc_charges":{"type":"u8","value":0},"proc_flags":{"type":"u32","value":0},"range_yd":{"type":"u32","value":0},"school_mask":{"type":"u8","value":4},"spell_level":{"type":"u8","value":52},"stances":{"type":"u8","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000100,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":33},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000100,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000101,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":71},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000101,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000102,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":129},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000102,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000103,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":224},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000103,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000104,"effect_index":0},"operation":"insert","fields":{"base_points":{"type":"i32","value":340},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":1},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.5},"period_ms":{"type":"u32","value":0},"radius_yd":{"type":"f32","value":8.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":4},"trigger_spell":{"type":"u32","value":0}}},{"table":"game_spell_effect","key":{"spell_id":6000104,"effect_index":1},"operation":"insert","fields":{"base_points":{"type":"i32","value":4},"chain_targets":{"type":"u8","value":0},"die_sides":{"type":"i32","value":0},"effect_mechanic":{"type":"u8","value":0},"enters_combat":{"type":"bool","value":false},"kind":{"type":"u8","value":129},"p0":{"type":"i32","value":0},"p0_kind":{"type":"u8","value":255},"p1":{"type":"i32","value":0},"per_level":{"type":"f32","value":0.0},"period_ms":{"type":"u32","value":3000},"radius_yd":{"type":"f32","value":0.0},"script_id":{"type":"u32","value":0},"target":{"type":"u8","value":1},"trigger_spell":{"type":"u32","value":0}}}]}
\ No newline at end of file
diff --git a/datascripts/src/fire_nova/spells.ts b/datascripts/tests/fixtures/fire_nova.ts
similarity index 70%
rename from datascripts/src/fire_nova/spells.ts
rename to datascripts/tests/fixtures/fire_nova.ts
index 9307245d3..813d5cdbf 100644
--- a/datascripts/src/fire_nova/spells.ts
+++ b/datascripts/tests/fixtures/fire_nova.ts
@@ -1,21 +1,4 @@
-// Fire Nova: the worked example of authoring spells as a Package Delta.
-//
-// It clones a real spell, changes what it needs, loops a rank ladder, and emits one artifact. Every
-// column below is named the way the Module declares it, so a schema move fails the typecheck here
-// rather than at import.
-//
-// Run it with `lyracore packages build`, or directly:
-//
-//   bun run datascripts/src/fire_nova/spells.ts
-//
-// The artifact lands at `packages/fire_nova/data/.generated/spell.json`. Only THIS file is
-// committed: the artifact is derived, and regenerating it is one command.
-//
-// # Why a clone
-//
-// A Package may not invent a spell out of nothing — an insert has to carry every column, and half a
-// row is not a spell. Cloning a real one gives a complete, coherent starting point, and every column
-// the author does not name keeps the source's value.
+// Five spell ranks for the Datascript emission and Rust interop tests. Uses a synthetic Base Snapshot.
 
 import { run } from "../../lib/index.ts";
 
diff --git a/docs/development-cli.md b/docs/development-cli.md
index 2ddc2f6f3..e0fe343bb 100644
--- a/docs/development-cli.md
+++ b/docs/development-cli.md
@@ -66,7 +66,7 @@ lyracore packages config NAME [KEY [VALUE]] [--new]
 lyracore packages disable NAME [--yes]
 lyracore packages enable NAME
 lyracore packages list
-lyracore packages new NAME
+lyracore packages new NAME [--from RUNG]
 lyracore packages remove NAME [--yes]
 lyracore packages replay [DATABASE ...] [--check] [--yes] [--force-all] [--client-data PATH]
 lyracore packages update [NAME] [--yes]
@@ -99,7 +99,7 @@ lyracore update
 | `packages disable` | run Package Teardown on every Shard, then move the Package out of the build's sight, keeping it on disk |
 | `packages enable` | move a disabled Package back into the build |
 | `packages list` | every installed Package: enabled or disabled, where it came from, and whether it has drifted |
-| `packages new` | scaffold a new Package offline, by copying and renaming the reference Package this checkout ships |
+| `packages new` | copy a Reference Package from the collection tag matching this checkout's Package API |
 | `packages remove` | delete a disabled Package, after a confirmation and a check for local changes |
 | `packages replay` | reapply every enabled Package's claims and Runtime Scripts onto the named Shards, or the whole recorded fixture topology by default |
 | `packages update` | advance a Git-backed Package, or every one of them, to the repository's current commit |
@@ -225,7 +225,8 @@ for you**, so a plain `./lyracore import` never asks twice.
 ./lyracore packages add https://host/greeter.git   # clone a repository whose root is one Package
 ./lyracore packages add greeter                # bare name: resolve from the Official Package Collection
 ./lyracore packages list
-./lyracore packages new my-package             # scaffold one from nothing but this checkout
+./lyracore packages new my-package             # start from example-script
+./lyracore packages new my-package --from example-rust
 ```
 
 A Package is a drop-in folder under `packages/<name>/`. `module/build.rs` discovers it and compiles
@@ -295,18 +296,24 @@ Identity, whether the tree on disk still matches it (`clean` or `LOCALLY DRIFTED
 registers. A Package with no stamp — dropped into `packages/` by hand, or installed before this
 command existed — renders as unrecorded rather than failing the listing.
 
-**`packages new NAME` scaffolds a Package with no network access and nothing external to review.**
-It copies `packages/example/` — the maintained reference Package every LyraCore checkout ships,
-including a fresh public clone — to `packages/NAME/`, renaming the reference's own identifiers into
-the new name, then writes a Provenance Stamp recording a **scaffold** origin rather than a Package
-Source (nothing external was installed, so there is nothing to name) and runs `preflight`. The same
-name and shape refusals as `add` apply before anything is written. The reference Package is
-Rust-only and inert. Its `src/mod.rs` carries one commented hook pattern, and the scaffold has no
-`client/` directory. The printed next steps say to add `client/addons/<Name>/` for addons or `client/mpq/`
-for client-file overrides, and that `client sync` will pack them in once you do. Growing the Rust
-half means wiring more hooks from the catalogue in `module/src/hooks.rs`, following the pattern
-`packages/NAME/src/mod.rs` already shows. A scaffold ships no Datascript: the authoring toolchain
-in `datascripts/` is checkout-wide today, not per-Package.
+`packages new NAME [--from RUNG]` fetches a Reference Package from the Official Package Collection.
+The checkout's Package API version selects its tag, as with `packages add`. The default is
+`example-script`, which needs no Rust. Other rungs are `example-client`, `example-data`,
+`example-rust` and `example-all`. A missing tag or rung leaves the Package Inventory unchanged.
+
+The command copies the source into `packages/NAME/`, renames Package names, Rust identifiers and
+client filenames, prints its Trust Review and runs `preflight`. The Provenance Stamp keeps the
+`scaffold` kind and records the chosen rung and exact collection revision. `packages update`
+does not replace scaffolded code.
+
+Rungs with Runtime Scripts or Datascripts need a lowercase Package name of at most 64 characters.
+Each `<name>.<script file stem>` must also fit the 64-character Runtime Script name limit.
+
+Generated artifacts are omitted because the renamed sources need new Build Identities. Before
+using a copy beside another, choose distinct `@id` values for Runtime Scripts or a distinct Package
+Spell ID in its Datascript. Run `packages build` after editing the sources. A Datascript also needs
+a Base Snapshot from your own client data. Replay the built artifacts through the normal realm
+update; use `client sync` for a client half. Scaffolding requires network access to the collection.
 
 ## `packages enable`, `disable`, `remove` — taking a Package out of the build
 
@@ -456,7 +463,8 @@ then up to eight steps, in this order:
    database.
 2. `bun install --frozen-lockfile` installs exactly what `datascripts/bun.lock` records. Frozen, so
    a build never silently resolves a newer dependency than the next author will get.
-3. `tsc --noEmit` is the typecheck gate. Nothing is emitted; the answer is the exit code.
+3. `tsc --noEmit` typechecks Core's Datascript project and each enabled Package's local Datascripts.
+   The CLI extends Core's compiler configuration in a temporary file. No JavaScript is emitted.
 
 Steps 4 to 8 run only when an enabled Package carries a Datascript or a Runtime Script. A checkout
 with neither builds exactly as it did before those steps existed:
@@ -465,8 +473,9 @@ with neither builds exactly as it did before those steps existed:
    fails fast with the exact `lyracore-importer --spell-snapshot` command to build one, once, rather
    than letting every Datascript fail with the same "cannot read" error in turn. Skipped when no
    Package has a Datascript: a Runtime Script reads no base data.
-5. Every enabled Package's Datascripts run, one `bun run` subprocess per file, in name order. The
-   first script to throw stops the build; later scripts and later Packages never run.
+5. Each enabled Package runs `datascripts/src/<name>/*.ts`, then
+   `packages/<name>/datascripts/*.ts`. Each directory runs in file-name order, with one `bun run`
+   subprocess per file. The first failure stops the build.
 6. Every enabled Package with a `scripts/` folder compiles its Runtime Scripts into one Script
    Artifact, one `bun run` subprocess per Package, in folder-name order. The builder is handed the
    Module's Event Binding catalogue, read from `lyracore-delta-check --print-events`, so a mistyped
@@ -520,6 +529,10 @@ the schema's authority.
 `src/reference.ts` is the standing schema check. It names real columns, so it is the file that fails
 when the schema moves under it. Keep it referencing real columns.
 
+A Package can ship `packages/<name>/datascripts/welcome.ts`. It imports the authoring library as
+`../../../datascripts/lib/index.ts`. The older `datascripts/src/<name>/` location still works.
+The Build Identity covers both source directories, so editing either requires a rebuild.
+
 ### Bun is author-side only
 
 `packages build` is the only command that needs Bun, and authoring Datascripts is the only reason
@@ -541,16 +554,16 @@ Runtime Script Host, with a Fuel Budget and no access to anything the Host did n
 one in TypeScript or in Lua:
 
 ```text
-packages/fire_nova/
+packages/example-script/
   scripts/
-    ember_echo.ts    compiled by the Runtime Script Toolchain
-    bonus.lua        shipped unchanged, for the author who would rather write Lua
+    welcome.ts       compiled by the Runtime Script Toolchain
+    ding.lua         shipped unchanged, for the author who would rather write Lua
   data/.generated/
-    fire_nova.script.json   the Script Artifact. Committed in the Official Package Collection
+    example-script.script.json   the Script Artifact. Committed in the Official Package Collection
 ```
 
-The sources live **inside** the Package, unlike a Datascript. A Datascript sits outside because only
-artifacts belong in a Package folder; a Runtime Script is the Package's own content.
+Runtime Script sources and Package-local Datascripts both live inside their Package. A Runtime
+Script runs on the realm; a Datascript runs on the author's machine.
 
 Every file opens with its **Script Directives**, `//` in TypeScript and `--` in Lua:
 
diff --git a/docs/package-api.md b/docs/package-api.md
index 142f93193..32bf60c69 100644
--- a/docs/package-api.md
+++ b/docs/package-api.md
@@ -5,7 +5,7 @@ wasm and can reach any `crate::` path the compiler resolves; this document says
 core will keep working, and `module/build.rs` fails the build on the rest.
 
 This is a contract, not a tutorial. Read `packages/README.md` for how a Package is installed and
-`packages/example/src/mod.rs` for the shape of one.
+[the Reference Packages](https://github.com/LyraCoreProject/packages#packages) for working examples.
 
 ## Compatibility promise
 
diff --git a/docs/schema.md b/docs/schema.md
index 89f275735..480176c8e 100644
--- a/docs/schema.md
+++ b/docs/schema.md
@@ -55,7 +55,7 @@ publish presents as an unrelated mid-session hang, not a loud "no such table".
 ## 2. Inventory
 
 **285 tables**, all of them in `module/src/**`: 128 public, 157 private. No table comes from a
-package in this tree; `packages/example` is the only in-tree package and it declares none. Recount
+Package in this tree. Packages are installed separately. Recount
 rather than trust the numbers below, which drift on every schema change. The pattern matches both
 `#[table(...)]` and the fully qualified `#[spacetimedb::table(...)]`; missing the second form
 undercounts. The second command lists the tables per file, which is what the rows below add up:
diff --git a/module/Cargo.toml b/module/Cargo.toml
index 292907ec6..0c7b456e4 100644
--- a/module/Cargo.toml
+++ b/module/Cargo.toml
@@ -19,6 +19,8 @@ crate-type = ["cdylib", "rlib"]
 # `--build-options` is forwarded verbatim to the wasm-target `cargo build`. `danger-zones.md` §3 is
 # authoritative on this accepted alpha posture.
 debug_reducers = []
+# Inert Package registration used only by the disposable integration-test Module.
+package_test_fixture = ["debug_reducers"]
 
 [dependencies]
 blake3 = "1"
diff --git a/module/build.rs b/module/build.rs
index 7c3b64eeb..5e9048659 100644
--- a/module/build.rs
+++ b/module/build.rs
@@ -1,9 +1,8 @@
 //! Build-time codegen for the module's self-registration registries.
 //!
 //! Scans every `.rs` file under `src/` AND under each drop-in package's `packages/<name>/src/`
-//! (repo root — `packages/` ships the maintained reference Package, `packages/example/`, even in
-//! the public mirror; every OTHER package is an operator's own private addition) for the three
-//! marker invocations and generates, into `$OUT_DIR`, the files the crate `include!`s:
+//! at the repository root for marker invocations. Packages are installed separately. Generates
+//! into `$OUT_DIR` the files the crate `include!`s:
 //!
 //! - `character_sweeps.rs` — from `character_owned!` markers: the two `&[fn(...)]`
 //!   const arrays `CHARACTER_OWNED_DELETE_SWEEPS` and `CHARACTER_OWNED_RESTAMP_SWEEPS`, plus
@@ -79,11 +78,6 @@
 use std::fs;
 use std::path::{Path, PathBuf};
 
-/// The folder name of the maintained reference Package (`packages/example/`) that
-/// `lyracore packages new` scaffolds from. It ships in every checkout, including the public
-/// mirror, and is deliberately excluded from the `has_packages` cfg — see its use below.
-const REFERENCE_PACKAGE: &str = "example";
-
 /// One row of the notify-hook event catalog.
 ///
 /// `actor`/`target` are the Runtime Script Event Binding half (#318): Rust expressions, evaluated
@@ -318,9 +312,6 @@ fn main() {
     let src_dir = Path::new(&manifest_dir).join("src");
     println!("cargo:rerun-if-changed={}", src_dir.display());
 
-    // packages/ lives at the repo root (module/'s parent), holding at minimum the reference
-    // Package (`example/`) — present in every checkout including the public mirror — so
-    // rerun-if-changed never points at a missing path here.
     let packages_dir = Path::new(&manifest_dir)
         .parent()
         .expect("module/ has a parent (the repo root)")
@@ -353,12 +344,11 @@ fn main() {
             let name = pkg.file_name().unwrap().to_string_lossy().into_owned();
             let pkg_src = pkg.join("src");
             if !pkg_src.is_dir() {
-                // A package needs no Rust half. A CLIENT-ONLY package (client/ — addons/FrameXML
-                // shipped by --pack-client) and a DATA-ONLY package (data/ — the Package Deltas a
-                // Datascript generates, applied by the importer) are both legal, quiet shapes. A
-                // package with none of the three is probably a typo'd `scr/` folder — warn loudly.
-                if !pkg.join("client").is_dir() && !pkg.join("data").is_dir() {
-                    println!("cargo:warning=packages/{name}: none of src/, client/ or data/ — nothing registered (typo'd folder?)");
+                if !["client", "data", "scripts", "datascripts"]
+                    .iter()
+                    .any(|part| pkg.join(part).is_dir())
+                {
+                    println!("cargo:warning=packages/{name}: none of src/, client/, data/, scripts/ or datascripts/; nothing registered");
                 }
                 continue;
             }
@@ -382,20 +372,20 @@ fn main() {
         }
     }
 
-    // `has_packages`: at least one drop-in package with Rust in it compiled into this crate, OTHER
-    // than the reference Package (`packages/example/`). A handful of `actor.rs` verbs and one
-    // `group.rs` emitter exist SOLELY for a real package to call (the same shape as the
-    // `debug_only!` verbs, whose only consumer is the feature-gated debug harness), so without this
-    // cfg a build with no such package — which, since the reference Package ships in every
-    // checkout, is now the common case rather than the packages-less one — reports them as unused
-    // imports and dead code. `packages/example/` never calls them, by design (it stays inert), so it
-    // is excluded here rather than counted. The check-cfg line is unconditional so rustc's
-    // `unexpected_cfgs` lint knows the name either way.
+    // Package-only actor verbs need no caller in a Core checkout with no installed Rust Package.
     println!("cargo::rustc-check-cfg=cfg(has_packages)");
-    if pkg_mods.iter().any(|(ident, _)| ident != REFERENCE_PACKAGE) {
+    if !pkg_mods.is_empty() {
         println!("cargo::rustc-cfg=has_packages");
     }
 
+    // Durable tests need a registered name for ownership and teardown, without installing content.
+    if std::env::var_os("CARGO_FEATURE_PACKAGE_TEST_FIXTURE").is_some() {
+        pkg_mods.push((
+            "test_fixture".to_string(),
+            Path::new(&manifest_dir).join("tests/fixtures/test_fixture.rs"),
+        ));
+    }
+
     let out_dir = std::env::var("OUT_DIR").expect("OUT_DIR is set by cargo");
 
     // ---- character_sweeps.rs (also fed by package markers) ----
diff --git a/module/src/actor.rs b/module/src/actor.rs
index cfaa60cc9..9020636f3 100644
--- a/module/src/actor.rs
+++ b/module/src/actor.rs
@@ -96,12 +96,8 @@ macro_rules! debug_only {
     };
 }
 
-// The same argument for the other optional consumer: `packages/` is a DROP-IN tree that build.rs
-// discovers at build time, and a checkout with no REAL package installed (only the inert reference
-// Package, `packages/example/`, which every checkout ships) is a designed, supported state — so a
-// verb whose only consumer is a package is not dead, it is unbuilt. build.rs emits `has_packages`
-// when it compiled at least one package OTHER than the reference one in; a build that DID gets the
-// lint back, which is still the cue to delete a verb nobody consumes rather than suppress it.
+// Package-only verbs need no caller when no Rust Package is installed. Restore the unused-import
+// lint when a Package is present so unused verbs remain visible during Package development.
 macro_rules! package_only {
     ($(pub(crate) use $path:path as $verb:ident;)+) => {
         $(
diff --git a/module/src/group.rs b/module/src/group.rs
index 0b2368bce..c5683fca6 100644
--- a/module/src/group.rs
+++ b/module/src/group.rs
@@ -316,10 +316,7 @@ pub struct BotInviteIntent {
 /// player's own CMSG_GROUP_INVITE is a pure gateway-side resolve-then-call with no module-side
 /// pre-check either.
 ///
-/// Its ONLY callers are Packages (see the `package_only!` macro in `actor.rs`): a
-/// build with no REAL package installed — the common case, since only the inert reference Package,
-/// `packages/example/`, ships by default — has no caller for this, which is a designed state, not
-/// dead code.
+/// Only Packages call this operation. A Core checkout without an installed Rust Package has no caller.
 #[cfg_attr(not(has_packages), allow(dead_code))]
 pub(crate) fn emit_bot_invite_intent(ctx: &ReducerContext, inviter_guid: u64, target_guid: u64) {
     emit_bot_group_intent(ctx, bot_op::INVITE, inviter_guid, target_guid);
diff --git a/module/src/lib.rs b/module/src/lib.rs
index f58a5616f..8148a3934 100644
--- a/module/src/lib.rs
+++ b/module/src/lib.rs
@@ -190,9 +190,8 @@ macro_rules! character_owned {
 
 /// Registers a periodic pass with the core scheduler tick pipeline. Same build.rs
 /// text-scan mechanism as the `character_owned` marker: write the invocation next to the code it
-/// drives (core src/ or a drop-in `packages/<name>/src/` file — every checkout has at least the
-/// reference Package, `packages/example/`) and the generated `GAME_TICK_PASSES` registry picks it
-/// up with zero core-file edits.
+/// drives, in core src/ or a drop-in `packages/<name>/src/` file. The generated `GAME_TICK_PASSES`
+/// registry picks it up with zero core-file edits.
 ///
 /// The ONE accepted shape (anything else fails the build loudly; commented-out/quoted marker
 /// syntax is inert — build.rs strips comments and strings before scanning):
diff --git a/module/src/test_scan.rs b/module/src/test_scan.rs
index f981e892a..6395776bb 100644
--- a/module/src/test_scan.rs
+++ b/module/src/test_scan.rs
@@ -298,12 +298,8 @@ pub(crate) fn repo_root() -> std::path::PathBuf {
 /// The optional directory a repo-relative path belongs to, if any — the ONLY directory whose
 /// absence licenses skipping that path.
 ///
-/// A drop-in package is optional ONE PACKAGE AT A TIME — a missing `packages/sample_package/src/goals.rs`
-/// inside an installed `packages/sample_package/` is a typo, not an uninstalled package — unlike the
-/// private-only tooling trees below, which are optional WHOLESALE. `packages/` itself is always
-/// there, in every checkout including the public mirror (it ships the reference Package,
-/// `packages/example/`), so only an individual OTHER package — `packages/<pkg>` — can be absent;
-/// every path under it still resolves correctly here because it maps to its own subpackage dir.
+/// Each installed Package owns its paths. A missing file within an installed Package is a defect;
+/// an absent Package is optional. The private tooling roots below are optional as a whole.
 fn optional_owner(rel: &str) -> Option<String> {
     let mut segs = rel.split('/');
     match segs.next()? {
diff --git a/module/tests/fixtures/test_fixture.rs b/module/tests/fixtures/test_fixture.rs
new file mode 100644
index 000000000..65c658792
--- /dev/null
+++ b/module/tests/fixtures/test_fixture.rs
@@ -0,0 +1 @@
+//! An inert Package for Core's durable ownership and teardown tests. No tables or hooks.
diff --git a/module/tests/package_account.rs b/module/tests/package_account.rs
index 94b01782d..fc96b35d4 100644
--- a/module/tests/package_account.rs
+++ b/module/tests/package_account.rs
@@ -5,7 +5,7 @@ mod support;
 
 use support::Standalone;
 
-const PACKAGE: &str = "example";
+const PACKAGE: &str = "test_fixture";
 
 fn arg(value: &str) -> String {
     serde_json::to_string(value).expect("a string encodes as JSON")
@@ -71,7 +71,7 @@ fn a_package_character_lands_on_an_account_that_records_its_package() {
         ));
         assert_eq!(account.len(), 1, "owned Account {account_id} is missing");
         assert!(
-            account[0]["username"].starts_with("example#"),
+            account[0]["username"].starts_with("test_fixture#"),
             "unexpected username: {account:?}"
         );
         assert_eq!(
@@ -127,7 +127,7 @@ fn a_new_package_account_skips_a_name_an_unowned_account_holds() {
     let shard = stage("package-account-taken-name");
     let first = create(&shard, "Bota", "1", "1");
     assert!(first.status.success(), "{first:?}");
-    // The Account `example#0` stays, but no longer counts as owned.
+    // The Account `test_fixture#0` stays, but no longer counts as owned.
     shard.assert_sql("DELETE FROM game_package_account");
 
     let second = create(&shard, "Botb", "1", "1");
@@ -141,5 +141,5 @@ fn a_new_package_account_skips_a_name_an_unowned_account_holds() {
         "SELECT username FROM game_account WHERE id = {}",
         owned[0]
     ));
-    assert_eq!(account[0]["username"], "example#1");
+    assert_eq!(account[0]["username"], "test_fixture#1");
 }
diff --git a/module/tests/package_runtime_scripts.rs b/module/tests/package_runtime_scripts.rs
index 5eb1ef0b2..4915608ec 100644
--- a/module/tests/package_runtime_scripts.rs
+++ b/module/tests/package_runtime_scripts.rs
@@ -101,7 +101,7 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
     apply(
         &standalone,
         &[artifact(
-            "example.bolt",
+            "test_fixture.bolt",
             HASH_A,
             &[
                 script(100_001, "bolt.greet", "on_login", 0, true, "local a = 1"),
@@ -117,7 +117,7 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
         "both scripts land, disabled or not: {rows:?}"
     );
     assert_eq!(rows[0].1, "bolt.greet");
-    assert_eq!(rows[0].2, "example.bolt");
+    assert_eq!(rows[0].2, "test_fixture.bolt");
     assert_eq!(rows[0].3, "on_login");
     assert_eq!(
         rows[0].4.len(),
@@ -128,14 +128,17 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
         rows[0].4, rows[1].4,
         "two different sources hash differently"
     );
-    assert_eq!(provenance(&standalone), [("example.bolt".to_string(), 2)]);
+    assert_eq!(
+        provenance(&standalone),
+        [("test_fixture.bolt".to_string(), 2)]
+    );
 
     // --- Re-applying the same plan is idempotent.
     let before = scripts_on_shard(&standalone);
     apply(
         &standalone,
         &[artifact(
-            "example.bolt",
+            "test_fixture.bolt",
             HASH_A,
             &[
                 script(100_001, "bolt.greet", "on_login", 0, true, "local a = 1"),
@@ -154,7 +157,7 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
         &standalone,
         &[
             artifact(
-                "example.bolt",
+                "test_fixture.bolt",
                 HASH_A,
                 &[script(
                     100_001,
@@ -166,7 +169,7 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
                 )],
             ),
             artifact(
-                "example.zeta",
+                "test_fixture.zeta",
                 HASH_B,
                 &[script(
                     100_050,
@@ -192,8 +195,8 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
     assert_eq!(
         provenance(&standalone),
         [
-            ("example.bolt".to_string(), 1),
-            ("example.zeta".to_string(), 1)
+            ("test_fixture.bolt".to_string(), 1),
+            ("test_fixture.zeta".to_string(), 1)
         ]
     );
 
@@ -201,7 +204,7 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
     apply(
         &standalone,
         &[artifact(
-            "example.zeta",
+            "test_fixture.zeta",
             HASH_B,
             &[script(
                 100_050,
@@ -214,9 +217,16 @@ fn a_packages_runtime_scripts_reconcile_onto_a_shard() {
         )],
     );
     let rows = scripts_on_shard(&standalone);
-    assert_eq!(rows.len(), 1, "example.bolt's scripts are gone: {rows:?}");
+    assert_eq!(
+        rows.len(),
+        1,
+        "test_fixture.bolt's scripts are gone: {rows:?}"
+    );
     assert_eq!(rows[0].1, "zeta.greet");
-    assert_eq!(provenance(&standalone), [("example.zeta".to_string(), 1)]);
+    assert_eq!(
+        provenance(&standalone),
+        [("test_fixture.zeta".to_string(), 1)]
+    );
 
     // --- An empty plan is the honest "no Package ships a script any more".
     apply(&standalone, &[]);
@@ -237,7 +247,7 @@ fn a_conflicting_plan_leaves_the_shard_exactly_as_it_was() {
     apply(
         &standalone,
         &[artifact(
-            "example.bolt",
+            "test_fixture.bolt",
             HASH_A,
             &[script(
                 100_001,
@@ -258,7 +268,7 @@ fn a_conflicting_plan_leaves_the_shard_exactly_as_it_was() {
             &arg("script"),
             &arg(&[
                 artifact(
-                    "example.first",
+                    "test_fixture.first",
                     HASH_A,
                     &[script(
                         100_002,
@@ -270,7 +280,7 @@ fn a_conflicting_plan_leaves_the_shard_exactly_as_it_was() {
                     )],
                 ),
                 artifact(
-                    "example.second",
+                    "test_fixture.second",
                     HASH_B,
                     &[script(
                         100_002,
@@ -295,7 +305,10 @@ fn a_conflicting_plan_leaves_the_shard_exactly_as_it_was() {
         before,
         "a refused plan writes nothing"
     );
-    assert_eq!(provenance(&standalone), [("example.bolt".to_string(), 1)]);
+    assert_eq!(
+        provenance(&standalone),
+        [("test_fixture.bolt".to_string(), 1)]
+    );
 }
 
 /// A Package Event is an event the Package fires itself, so the Shard has to store the binding
@@ -311,12 +324,12 @@ fn a_package_binds_its_own_event_and_never_another_packages() {
     apply(
         &standalone,
         &[artifact(
-            "example",
+            "test_fixture",
             HASH_A,
             &[script(
                 100_001,
-                "example.chooser",
-                "example.answer",
+                "test_fixture.chooser",
+                "test_fixture.answer",
                 0,
                 true,
                 "return 42",
@@ -327,23 +340,23 @@ fn a_package_binds_its_own_event_and_never_another_packages() {
     let rows = scripts_on_shard(&standalone);
     assert_eq!(rows.len(), 1, "{rows:?}");
     assert_eq!(
-        rows[0].3, "example.answer",
+        rows[0].3, "test_fixture.answer",
         "the Package Event is the dispatch label, so it is stored as written: {rows:?}"
     );
     let before = scripts_on_shard(&standalone);
 
-    // `example.bolt` reaching for `example`'s event. Refused at the parse, before any write.
+    // `test_fixture.bolt` reaching for `test_fixture`'s event. Refused at the parse, before any write.
     let refused = standalone.call(
         "apply_package_deltas",
         &[
             &arg("script"),
             &arg(&artifact(
-                "example.bolt",
+                "test_fixture.bolt",
                 HASH_B,
                 &[script(
                     100_002,
                     "bolt.thief",
-                    "example.answer",
+                    "test_fixture.answer",
                     0,
                     true,
                     "return 1",
@@ -361,7 +374,7 @@ fn a_package_binds_its_own_event_and_never_another_packages() {
         before,
         "a refused plan writes nothing"
     );
-    assert_eq!(provenance(&standalone), [("example".to_string(), 1)]);
+    assert_eq!(provenance(&standalone), [("test_fixture".to_string(), 1)]);
 }
 
 /// The point of the whole feature: a script a Package shipped runs at a real core chokepoint, and
@@ -393,7 +406,7 @@ fn a_package_script_fires_on_a_real_event_and_a_failing_one_does_not_block_the_n
     apply(
         &standalone,
         &[artifact(
-            "example.bolt",
+            "test_fixture.bolt",
             HASH_A,
             &[
                 script(
diff --git a/module/tests/package_teardown.rs b/module/tests/package_teardown.rs
index 605dce2f7..049ae2874 100644
--- a/module/tests/package_teardown.rs
+++ b/module/tests/package_teardown.rs
@@ -1,10 +1,10 @@
-//! `teardown_package` against a real Shard, with the reference Package as the Package torn down.
+//! `teardown_package` against a real Shard, with Core's inert fixture Package.
 
 mod support;
 
 use support::Standalone;
 
-const PACKAGE: &str = "example";
+const PACKAGE: &str = "test_fixture";
 
 fn arg(value: &str) -> String {
     serde_json::to_string(value).expect("a string encodes as JSON")
diff --git a/packages/README.md b/packages/README.md
index b8b6e4b21..b164d9358 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -1,76 +1,72 @@
-# packages/
+# Packages
 
-Every folder here is an ENABLED Package: `module/build.rs` compiles its `src/` into the module wasm
-and `lyracore client sync` packs its `client/` into your game client. No manifest lists them — this
-directory listing is the enabled set.
+Each folder here is an enabled Package. The build compiles its `src/` into the Module, and
+`lyracore client sync` installs its `client/` half. A Package can also contain Runtime Script
+sources in `scripts/`, Datascript sources in `datascripts/`, or generated artifacts in
+`data/.generated/`. Any one of these is enough. Core ships no enabled Packages.
 
-`example/` is the maintained reference Package. `lyracore packages new <name>` copies and renames it
-to scaffold a new one; read its `src/mod.rs` for the structure a Package's Rust half follows.
+Start with the Reference Package ladder in the
+[Official Package Collection](https://github.com/LyraCoreProject/packages#packages):
 
-`docs/package-api.md` is the Package API: the versioned list of what a Package's Rust half may call,
-and what core promises about it. The build lints every file here against that list and fails on a
-path outside it, naming the Package, the file and the line.
+| Rung | Example |
+| --- | --- |
+| `example-script` | TypeScript welcome on login and Lua welcome on level-up |
+| `example-client` | A client addon and a UI Transform |
+| `example-data` | A Datascript that clones one spell |
+| `example-rust` | A Rust hook, Package Config and a Package test |
+| `example-all` | Rust asks a Runtime Script, with Package Config as the fallback |
 
-A Package may also have a DATA half: `data/.generated/*.json`, the Package Deltas a Datascript
-generates, which the importer reapplies after every base import. `fire_nova/` is the worked example;
-its Datascript lives at `datascripts/src/fire_nova/spells.ts`, because only artifacts belong inside
-a Package folder. Any one half — `src/`, `client/`, `scripts/` or `data/` — is a valid Package on
-its own.
+```bash
+./lyracore packages new my-welcome
+./lyracore packages new my-welcome --from example-rust
+./lyracore packages add example-script
+```
+
+`new` defaults to `example-script`. Both `new` and a bare-name `add` fetch the collection tag
+matching the Package API version in [`docs/package-api.md`](../docs/package-api.md). A missing tag
+refuses the operation. The Provenance Stamp records the collection revision; a scaffold also
+records its rung and remains the author's own copy. `packages update` can advance an installed
+Official Package Source at the compatible tag, but does not replace a scaffold.
+
+A folder or Git URL passed to `packages add` keeps its own source rules. Review a Package as you
+would a Core patch. Its Rust is trusted Module code.
 
-A Package may also ship RUNTIME SCRIPTS: `scripts/*.ts` and `scripts/*.lua`, Lua the Module runs on
-a gameplay event inside the Runtime Script Host. These sources DO live inside the Package, unlike a
-Datascript, because they are the Package's own content rather than a description of client-derived
-data. `lyracore packages build` compiles them into one Script Artifact at
-`data/.generated/<name>.script.json`. `fire_nova/scripts/ember_echo.ts` is the worked example; it
-ships switched off. Each file opens with its Script Directives:
+## Building source
+
+`lyracore packages build` runs Package-local `datascripts/*.ts` as well as Core's legacy
+`datascripts/src/<package>/*.ts`. Datascripts use the Authoring Library and a Base Snapshot from
+your own client data. Their Package Deltas and Build Identities stay local under `data/.generated/`.
+Never commit a Package Delta to the collection.
+
+Runtime Scripts use `scripts/*.ts` or `scripts/*.lua`. The build compiles them into a Script
+Artifact and records its Build Identity. These two files may be committed to the collection.
+Each source starts with an event and a durable Script ID:
 
 ```ts
-// @event on_cast_resolved
-// @id 100200
-// @priority 10
-// @enabled false
+// @event on_login
+// @id 100300
 ```
 
-`@event` and `@id` are required, `@priority` defaults to 0 and `@enabled` to true. A TypeScript
-script declares `function script(): number | void`; what it returns is the Script Answer the asking
-Package reads back. See `docs/development-cli.md` for the Host API, the identifier band and how the
-build checks an event name against the Module.
-
-A Package that must change a stock FrameXML or GlueXML file declares the edit in
-`client/ui-transforms.json` instead of shipping a whole replacement under `client/mpq/`. Each entry
-names a path under `Interface/FrameXML/` or `Interface/GlueXML/`, one anchor (`before`, `after` or
-`replace`) that must occur exactly once in the file, and the text to insert. Two Packages may edit
-one file while their anchors stay apart. `lyracore client sync` composes the edits against your own
-client's stock bytes, which makes the result baseline-derived: it reaches your client only, and
-`lyracore client pack` refuses to put it in a distributable artifact. See
-`docs/development-cli.md` for the anchors, the conflict rules and the load order.
-
-`lyracore packages disable <name>` moves a folder out of here into `.lyracore/packages-disabled/`,
-where the build cannot see it, and `lyracore packages enable <name>` moves it back. The location is
-the enabled state, so this listing stays the whole truth about what compiles.
-
-`lyracore packages add <git-url>` installs a Package from a repository whose root is the Package
-itself, and records the commit it came from. `lyracore packages update <name>` advances that Package
-to the repository's current commit, keeping the old folder until the new one preflights.
-
-`lyracore packages add <name>` installs a first-party Package by bare name instead, resolved from
-the Official Package Collection (`LyraCoreProject/packages`) and pinned to the commit it was
-resolved at. `packages update` does not advance this kind.
-
-See `docs/development-cli.md` for `lyracore packages add`, `list`, `new`, `enable`, `disable`,
-`remove`, and `update`.
-
-## Operator-tunable config
-
-A Package that wants a value the Operator can change without a republish seeds it as Package
-Config: call `crate::package_config::ensure_package_config_default(ctx, "<your package>", "<key>",
-"<default value>")` from your own ensure/init path, every time it runs. The call only inserts when
-the row is absent, so a repeated call never clobbers a value the Operator has since edited.
-`spacetime sql "select * from game_package_config"` then shows real keys with live values, not a
-blank slate someone has to populate by hand.
-
-The Operator changes a value with the `set_package_config` reducer (`package_name, key, value,
-allow_new`). It refuses an unknown `(package_name, key)` pair — naming the package's existing keys —
-unless `allow_new` is set, so a typo in the key name fails loud instead of writing a key nobody
-reads. A dedicated CLI verb for this reducer is planned (#370); until then, call it directly with
-`spacetime call`.
+Optional `@priority` defaults to `0`, and `@enabled` defaults to `true`. TypeScript declares
+`function script(): number | void`. A numeric Script Answer is what a Package reads through
+`ask()`. Choose distinct IDs before installing multiple copies of a rung. After scaffolding,
+run `packages build` to produce artifacts for the renamed source.
+
+## Client content
+
+Put addons under `client/addons/<Name>/`. A UI Transform in `client/ui-transforms.json` inserts
+text at one unique `before`, `after` or `replace` anchor in a FrameXML or GlueXML Baseline.
+`client sync` composes it against your own client's bytes. `client pack` refuses to distribute
+that derived output. The client rung supplies an insertion, never a copied Baseline.
+
+## Config and location
+
+Rust Packages seed Package Config with `ensure_package_config_default` and read it through
+`game_package_config`. Seeding preserves a value the Operator already changed. On a development
+topology, `lyracore packages config NAME KEY VALUE` changes it without a republish.
+
+`packages disable` runs Package Teardown and moves the folder to `.lyracore/packages-disabled/`.
+`packages enable` moves it back. Folder location is the enabled state.
+
+See the [CLI commands](https://github.com/LyraCoreProject/lyracore-cli/blob/main/docs/commands.md)
+for build, replay, client installation and Package management.
diff --git a/packages/example/src/mod.rs b/packages/example/src/mod.rs
deleted file mode 100644
index 3eb2d07d1..000000000
--- a/packages/example/src/mod.rs
+++ /dev/null
@@ -1,23 +0,0 @@
-//! Reference Package: the maintained template `lyracore packages new <name>` copies and renames.
-//! Read it, don't just run it — it is documentation as much as it is code.
-//!
-//! A Package is a folder under `packages/<name>/` that `module/build.rs` discovers with zero
-//! core-file edits. `src/mod.rs` is its Rust root: the build generates `pub mod pkg_<name>` for it
-//! and compiles the module in. Nested submodule files also work; see `module/build.rs`'s scan doc
-//! for the facade re-export they must follow (this reference Package is one file, so it doesn't
-//! need one).
-//!
-//! The commented hook below shows the shape without registering dormant gameplay behavior. Pick an
-//! event from the catalog at the top of `module/src/hooks.rs`, uncomment the pattern, and implement
-//! the behavior the Package needs.
-//!
-//! A Package may also ship a `client/` directory (addons and client overrides, installed by
-//! `lyracore client sync`). This reference Package deliberately has none — `lyracore packages new`
-//! prints how to add one.
-//!
-//! ```ignore
-//! crate::game_hook!(on_group_invite, fn example_on_group_invite(ctx, payload) {
-//!     // Read `payload.target_guid` and `payload.inviter_guid`, then call the same core operation
-//!     // that handles the equivalent built-in behavior.
-//! });
-//! ```
diff --git a/packages/fire_nova/README.md b/packages/fire_nova/README.md
deleted file mode 100644
index ffd7d245c..000000000
--- a/packages/fire_nova/README.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# fire_nova
-
-The worked example of a DATA-ONLY Package: no Rust, no client half, one Package Delta and one
-Script Artifact.
-
-Its data is authored in `datascripts/src/fire_nova/spells.ts`, which clones a real spell into a
-five-rank ladder of Package spells. Its one Runtime Script is `scripts/ember_echo.ts`, which ships
-switched off. Read those two files — they are the example.
-
-Nothing under `data/` is committed. `lyracore packages build` runs the Datascript, compiles the
-Runtime Scripts and writes both artifacts; the importer reapplies them after every spell import.
-Build them yourself:
-
-```
-lyracore-importer --dbc <client Data/ dir> --spell-snapshot datascripts/generated/base-snapshot.json
-bun run datascripts/src/fire_nova/spells.ts
-bun run datascripts/runtime-scripts/build-scripts.ts fire_nova
-lyracore-delta-check packages/fire_nova/data/.generated/*.json
-```
-
-An unmodified client shows no tooltip for a Package spell: it renders spells from its own
-`Spell.dbc`, which has never heard of one. The identifiers are safe because nothing else can own
-them, not because the client knows them.
diff --git a/packages/fire_nova/data/.gitkeep b/packages/fire_nova/data/.gitkeep
deleted file mode 100644
index e69de29bb..000000000
diff --git a/packages/fire_nova/scripts/ember_echo.ts b/packages/fire_nova/scripts/ember_echo.ts
deleted file mode 100644
index b77886db0..000000000
--- a/packages/fire_nova/scripts/ember_echo.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-// @event on_cast_resolved
-// @id 100200
-// @enabled false
-//
-// The worked example of a Runtime Script. It ships SWITCHED OFF: `on_cast_resolved` fires for every
-// cast on a realm, and a demonstration should not talk to every player who casts anything. Switch
-// it on by changing the directive above and running `lyracore packages build`.
-//
-// What it shows: reading the event's entities, a Host Verb, and a Script Answer.
-
-/// How loudly the echo lands, as a share of the caster's remaining health.
-function echoShare(caster: Entity): number {
-  if (caster.max_health === 0) return 0;
-  return Math.floor((caster.health * 100) / caster.max_health);
-}
-
-function script(): number | void {
-  const caster = event.actor;
-  if (!caster || !caster.is_player) return;
-
-  const share = echoShare(caster);
-  const words = ["fire", "nova", "echo"];
-  send_chat(caster, words.join(" ") + ": " + share);
-  return share;
-}

From 4a98f155dc1e57562b0d652e307c9049cff109eb Mon Sep 17 00:00:00 2001
From: Mathih13 <mhartveit61@gmail.com>
Date: Sat, 10 Oct 2026 14:35:47 +0200
Subject: [PATCH 2/5] docs(packages): describe source rungs and the private
 test fixture

---
 CONTEXT.md                             | 2 +-
 crates/lyracore-test-support/README.md | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index d7c38ebf5..40357e9b0 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -920,7 +920,7 @@ _Avoid_: weather event, weather state table
 ### Packages
 
 **Package**:
-A drop-in folder under `packages/<name>/` that adds content to the realm with no core-file edits. Its `src/` is compiled into the Module wasm by the build's own discovery; its `client/` half supplies addons, whole-file client overrides and UI Transforms to the client packer. Either half alone is a valid Package.
+A drop-in folder under `packages/<name>/` that adds content to the realm with no core-file edits. Its `src/` is compiled into the Module wasm by the build's own discovery; its `client/` half supplies addons, whole-file client overrides and UI Transforms to the client packer. A Package can also carry Runtime Scripts in `scripts/`, Datascripts in `datascripts/`, and generated artifacts in `data/.generated/`. Any one of these parts is enough.
 Its data changes ship as Package Deltas rather than as edits to the base data.
 Package-specific tests live with the Package. Core supplies reusable private integration fixtures;
 the Package's test runner selects the Core checkout and owns its compatibility checks.
diff --git a/crates/lyracore-test-support/README.md b/crates/lyracore-test-support/README.md
index 2344f987e..6fa66cc90 100644
--- a/crates/lyracore-test-support/README.md
+++ b/crates/lyracore-test-support/README.md
@@ -3,6 +3,8 @@
 `Standalone` owns an isolated SpacetimeDB process, CLI configuration and database storage. Tests
 can publish the selected Core Module, call reducers, read durable state and retain failure logs.
 `module_bytes()` and `gateway_binary()` build the tested artifacts once per test process.
+The test Module enables `debug_reducers` and `package_test_fixture`. The latter registers an inert
+Package named `test_fixture` for Core's ownership and teardown tests; normal publishes omit it.
 
 Core tests use this crate's workspace. Package test runners set `LYRACORE_TEST_CORE` to the explicit
 Core checkout used for both builds and evidence. Package-specific setup and assertions belong in

From e9bbd9553952425443636adc721e8f0f910988e2 Mon Sep 17 00:00:00 2001
From: Mathih13 <mhartveit61@gmail.com>
Date: Sat, 10 Oct 2026 14:40:10 +0200
Subject: [PATCH 3/5] test(packages): remove the in-tree script source check

---
 datascripts/tests/runtime-scripts.test.ts | 37 ++---------------------
 1 file changed, 2 insertions(+), 35 deletions(-)

diff --git a/datascripts/tests/runtime-scripts.test.ts b/datascripts/tests/runtime-scripts.test.ts
index 654d6a7dd..6434f7eac 100644
--- a/datascripts/tests/runtime-scripts.test.ts
+++ b/datascripts/tests/runtime-scripts.test.ts
@@ -37,13 +37,12 @@ interface Built {
 async function build(
   files: Record<string, string>,
   events?: string[],
-  packageName = PACKAGE,
 ): Promise<Built> {
   const root = mkdtempSync(join(tmpdir(), "lyracore-runtime-scripts-"));
   const previousRoot = process.env.LYRACORE_PACKAGES_ROOT;
   const previousEvents = process.env.LYRACORE_HOOK_EVENTS;
   try {
-    const scripts = join(root, packageName, "scripts");
+    const scripts = join(root, PACKAGE, "scripts");
     mkdirSync(scripts, { recursive: true });
     for (const [name, source] of Object.entries(files)) {
       const path = join(scripts, name);
@@ -54,7 +53,7 @@ async function build(
     if (events === undefined) delete process.env.LYRACORE_HOOK_EVENTS;
     else process.env.LYRACORE_HOOK_EVENTS = events.join("\n");
 
-    const artifact = readFileSync(await buildPackageScripts(packageName), "utf8");
+    const artifact = readFileSync(await buildPackageScripts(PACKAGE), "utf8");
     return { artifact, scripts: JSON.parse(artifact).scripts };
   } finally {
     if (previousRoot === undefined) delete process.env.LYRACORE_PACKAGES_ROOT;
@@ -81,38 +80,6 @@ test("the committed fuel workload Lua is what the pinned toolchain emits today",
   expect(built.scripts[0]?.source).toBe(committed);
 });
 
-test("every checked-in Package Runtime Script passes through the pinned compiler", async () => {
-  const packagesRoot = join(import.meta.dir, "..", "..", "packages");
-  const packageScripts = readdirSync(packagesRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .sort((a, b) => a.name.localeCompare(b.name))
-    .flatMap((entry) => {
-      const scriptsDir = join(packagesRoot, entry.name, "scripts");
-      let sources;
-      try {
-        sources = readdirSync(scriptsDir, { withFileTypes: true });
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-        throw error;
-      }
-      const files = Object.fromEntries(
-        sources
-          .filter(
-            (source) =>
-              source.isFile() && (source.name.endsWith(".ts") || source.name.endsWith(".lua")),
-          )
-          .sort((a, b) => a.name.localeCompare(b.name))
-          .map((source) => [source.name, readFileSync(join(scriptsDir, source.name), "utf8")]),
-      );
-      return Object.keys(files).length === 0 ? [] : [{ package: entry.name, files }];
-    });
-
-  expect(packageScripts.length).toBeGreaterThan(0);
-  for (const checkedIn of packageScripts) {
-    await build(checkedIn.files, undefined, checkedIn.package);
-  }
-});
-
 // ---- determinism ----
 
 test("two builds of one source tree write the same bytes", async () => {

From 93aa242c5b1f2147f973f10a8e3c93a4506d61d0 Mon Sep 17 00:00:00 2001
From: Mathih13 <mhartveit61@gmail.com>
Date: Sat, 10 Oct 2026 14:58:04 +0200
Subject: [PATCH 4/5] docs(packages): describe official updates and local
 Datascripts

---
 docs/development-cli.md | 53 ++++++++++++++++++++---------------------
 1 file changed, 26 insertions(+), 27 deletions(-)

diff --git a/docs/development-cli.md b/docs/development-cli.md
index e0fe343bb..1e7b37c46 100644
--- a/docs/development-cli.md
+++ b/docs/development-cli.md
@@ -102,7 +102,7 @@ lyracore update
 | `packages new` | copy a Reference Package from the collection tag matching this checkout's Package API |
 | `packages remove` | delete a disabled Package, after a confirmation and a check for local changes |
 | `packages replay` | reapply every enabled Package's claims and Runtime Scripts onto the named Shards, or the whole recorded fixture topology by default |
-| `packages update` | advance a Git-backed Package, or every one of them, to the repository's current commit |
+| `packages update` | update Git Package Sources from their repository and Official Package Sources from the compatible collection tag |
 | `character gm` | flip GM commands on or off for a character, on whichever world shard has it |
 | `production status` | read-only checks for an explicitly named production topology and the latest gateway start |
 | `service reconcile` | make a production host's Standalone Supervisor match the unit tracked in this checkout. Root only |
@@ -236,8 +236,8 @@ around saying so.
 
 **Everything that can refuse the install happens before anything is copied.** The name must be one
 the build accepts (`[a-zA-Z][a-zA-Z0-9_-]*` — the build maps `my-package` onto the module
-`pkg_my_package` and panics on anything else). The shape must be one the build accepts: client-only
-and Rust-only are both valid, and when `src/` exists, `src/mod.rs` is required. The name must
+`pkg_my_package` and panics on anything else). A Package must carry `src/`, `client/`, `data/`,
+`scripts/` or `datascripts/`. When `src/` exists, `src/mod.rs` is required. The name must
 collide with neither the enabled nor the disabled inventory, compared on the Rust identifier rather
 than the folder name — `my-package` and `my_package` fold onto the same module.
 
@@ -245,10 +245,10 @@ Then it prints a **Trust Review** and asks. The review is a deterministic, read-
 candidate folder using a port of the build's own marker scan, so a commented-out or quoted marker
 registers nothing here either. It reports tables, reducers, hooks, tick passes, character-owned
 sweeps, addons, client overrides and Runtime Script sources. Runtime Scripts are named because they
-run on the realm once the Package is built. A Package cannot ship a Datascript of its own — the
-authoring toolchain lives in `datascripts/`, outside any Package folder — so that row is an explicit
-"none detected" rather than silence. The review states plainly that everything else in the Package's
-Rust is trusted code and that it is an inventory, not a security guarantee.
+run on the Realm once the Package is built. It also names Package-local Datascripts, which
+`packages build` runs as trusted code on the author's machine. The review states plainly that
+everything else in the Package's Rust is trusted code and that it is an inventory, not a security
+guarantee.
 
 On confirmation the folder is **copied, never symlinked**: a linked Package would compile from a
 folder outside the checkout, so `preflight`, `publish` and `client sync` would each read whatever
@@ -271,14 +271,14 @@ waiting on a hidden prompt.
 **A bare word that is not a path on this machine is an Official Package Source.** `packages add
 greeter` resolves `greeter` against the one Official Package Collection this CLI knows,
 `LyraCoreProject/packages`, which holds several first-party Packages side by side, one top-level
-directory each. The collection is cloned the same way a Git Package Source is, the named directory
-goes through the same Trust Review and consent question as any other install, and the rest of the
-clone is discarded. An unknown name is refused before anything is copied; a name that only differs
+directory each. The version in the checkout's `docs/package-api.md` selects a tag such as `api-v1`.
+The CLI fetches that tag and sends the named directory through the same Trust Review and consent
+question as any other install. A missing tag refuses the install; the rest of the clone is
+discarded. An unknown name is refused before anything is copied; a name that only differs
 from one already in the collection by hyphen/underscore folding is named in the refusal instead of
 installed in its place. The Provenance Stamp records the collection's URL and the exact commit the
-directory was resolved at. That commit is pinned at install time: `packages update` refuses this
-kind by name (see below), so a later commit to the collection can never silently change what is
-installed. Picking up a newer one means removing the Package and adding it again.
+directory was resolved at. `packages update` can advance the installed Package to the current
+commit at the compatible tag, after the normal Trust Review and confirmation.
 
 **It publishes nothing.** The two remaining steps are printed for you to run:
 
@@ -379,25 +379,25 @@ Save them outside the checkout first, or delete the folder by hand.
 
 **None of the three publishes or synchronizes a client.** Each prints the steps it did not run.
 
-## `packages update` — advancing a Git-backed Package
+## `packages update`
 
 ```bash
 ./lyracore packages update my-package        # advance one Package, asks first
-./lyracore packages update                   # advance every Git-backed Package
+./lyracore packages update                   # advance every Git or Official Package Source
 ./lyracore packages update --yes             # answer the questions in advance
 ```
 
-**Only a Git-backed Package can be updated.** With a name, anything else is refused by name and told
-why: a Package installed from a local folder has no newer revision to fetch, a scaffold has no
-Package Source at all, an Official Package Source has its commit pinned at install time on purpose,
-and a Package Source kind this CLI does not otherwise know is not cloned on the chance that it might
-be a repository. With no name, `update` walks both inventories and takes the Git-backed Packages,
-disabled ones included. A disabled Package that comes back later should not bring an old revision
-with it.
+Git Package Sources and Official Package Sources can be updated. With a name, other source kinds
+are refused: a local folder has no remote revision to fetch, a scaffold contains code the author
+owns, and an unknown source kind is not cloned. With no name, `update` selects both supported
+source kinds from the enabled and disabled inventories.
 
-Each update clones the recorded repository and compares the commit it finds against the recorded
-one. Same commit, nothing to do. A newer commit gets the same Trust Review and the same question as
-an install, and the question names both commits.
+A Git Package Source uses the recorded repository's current commit. An Official Package Source
+uses the tag matching the checkout's Package API version and resolves the same Package name there.
+A missing tag or Package refuses the update before changing the installed copy.
+
+If the resolved commit matches the Provenance Stamp, there is nothing to do. A different commit
+gets the same Trust Review and confirmation as an install, with both commits named.
 
 **A folder that has drifted from its Provenance Stamp is refused, and nothing is discarded.** An
 update replaces the whole folder, so it may only run when every byte in that folder is recorded
@@ -410,8 +410,7 @@ then is the old folder deleted. If anything fails, the previous revision goes ba
 the candidate is discarded, and the error names both commits. `update` publishes nothing and
 synchronizes no client; it prints the steps it did not run.
 
-Applying and replaying Package Deltas is `packages replay`, below. Advancing an Official Package
-Source through `packages update` remains separate work.
+Applying and replaying Package Deltas is `packages replay`, below.
 
 ## `packages config` — a Package's key-values, on every Shard
 

From 6a5310717625f575f5c99a2ad76f73d4aee739b2 Mon Sep 17 00:00:00 2001
From: Mathih13 <mhartveit61@gmail.com>
Date: Sat, 10 Oct 2026 14:59:09 +0200
Subject: [PATCH 5/5] docs(packages): clarify checks for disabled updates

---
 docs/development-cli.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/development-cli.md b/docs/development-cli.md
index 1e7b37c46..7b2f8372c 100644
--- a/docs/development-cli.md
+++ b/docs/development-cli.md
@@ -405,8 +405,8 @@ somewhere else. That is `packages remove`'s rule, for the same reason: local edi
 copy are recorded nowhere, and neither command can get them back.
 
 **The previous revision is kept until the new one is proven.** The old folder moves out of the
-inventory, the new revision installs in its place, and `preflight` runs with it compiled in. Only
-then is the old folder deleted. If anything fails, the previous revision goes back byte for byte,
+inventory, the new revision installs in its place, and `preflight` runs. A disabled Package stays
+disabled and is excluded from compilation. The old folder is deleted only after `preflight` passes. If anything fails, the previous revision goes back byte for byte,
 the candidate is discarded, and the error names both commits. `update` publishes nothing and
 synchronizes no client; it prints the steps it did not run.