diff --git a/entity-foundations/README.md b/entity-foundations/README.md
new file mode 100644
index 0000000..dd75ae5
--- /dev/null
+++ b/entity-foundations/README.md
@@ -0,0 +1,26 @@
+# Entity foundations
+
+Two equivalent component scripts exercise live shared runtime services. Use one at
+a time; this is a runnable script demonstration, not a serialized starter project.
+
+1. Build/install the engine branch linked in the companion pull request (an older
+   release will not contain Tags/Groups/Entity/Components).
+2. Create a project and a scene object in the Rustic editor.
+3. Use **Programming > New Script > Object Component Script**, choose Lua or Python,
+   and replace the generated source with `behavior.lua` or `behavior.py` here.
+4. Attach that script to the object with **+ Add Component** or by dragging it from
+   Explorer onto the object. Do not edit the scene/manifest metadata manually.
+5. Press **Play**. Expect `entity foundations ready` in the Console; the object
+   disappears after one scaled fixed second. Stop Play to restore it.
+
+Lua is bundled. Python needs the existing Python 3 toolchain. The engine supplies
+`rustic.py`; do not install an unrelated Python package. Keep only one tagged
+`enemy` object while running this example, because it asserts exactly one match.
+Tags and groups exist only during Play and are not stored in authored scenes.
+Paused Play/Clock pause stops the countdown. UI/global scripts should pass a real
+scene ID instead of using their synthetic owner.
+
+The companion engine tests execute both scripts against a live SceneWorld, check
+that registration reaches Rust, and check destruction and group cleanup. See the
+[API reference](https://rustic-game-engine.pages.dev/docs/api/entity-foundations)
+for every signature, errors, language differences and limitations.
diff --git a/entity-foundations/behavior.lua b/entity-foundations/behavior.lua
new file mode 100644
index 0000000..54a88fd
--- /dev/null
+++ b/entity-foundations/behavior.lua
@@ -0,0 +1,11 @@
+return {Start=function()
+    local e=rustic.entity_id()
+    Tags.add(e,'enemy')
+    Groups.create('enemies')
+    Groups.add('enemies',e)
+    assert(Entity.is_valid(e))
+    assert(Components.has(e,'rustic.transform'))
+    assert(#Tags.find_all('enemy')==1)
+    rustic.log('info','entity foundations ready')
+    Entity.destroy_after(e,1)
+end}
diff --git a/entity-foundations/behavior.py b/entity-foundations/behavior.py
new file mode 100644
index 0000000..d52d9aa
--- /dev/null
+++ b/entity-foundations/behavior.py
@@ -0,0 +1,14 @@
+from rustic import rustic, Tags, Groups, Entity, Components, run
+
+def on_start():
+    e = rustic.entity_id()
+    Tags.add(e, 'enemy')
+    Groups.create('enemies')
+    Groups.add('enemies', e)
+    assert Entity.is_valid(e)
+    assert Components.has(e, 'rustic.transform')
+    assert len(Tags.find_all('enemy')) == 1
+    rustic.log('info', 'entity foundations ready')
+    Entity.destroy_after(e, 1)
+
+run(globals())