diff --git a/docs/modding.md b/docs/modding.md
index 7c724404..1a2251b0 100644
--- a/docs/modding.md
+++ b/docs/modding.md
@@ -265,6 +265,80 @@ Red exposes FLY separately because it requires a destination picker:
 and `mod.world:flyTo(mapId)` accepts only a visited destination from the native
 Fly town list. Gold does not expose these two methods yet.
 
+## Self-driven world actors
+
+`mod.world:spawnNpc()` returns a handle whose `scriptMove` queues onto the
+overworld's scripted-movement list. A non-empty list is how the overworld
+knows a cutscene is running, so it gates player input for as long as the
+actor walks -- right for Oak marching to his lab, wrong for an actor that
+moves on its own schedule (a networked player's ghost, an ambient walker).
+Five handle methods drive one without that lockout:
+
+```lua
+local ghost = mod.world:spawnNpc({ map = "ROUTE_1", x = 5, y = 7,
+                                   sprite = "SPRITE_RED" })
+if ghost:canStep("up") then ghost:stepNow("up") end   -- one tile, now
+if not ghost:isMoving() then ghost:placeAt(9, 3, "down") end  -- snap, no walk
+ghost:setPassable(true)                               -- walk-through
+```
+
+`stepNow(dir)` sets the same per-tile state `scriptMove` does, minus the
+queue. It deliberately does **not** check collision: a caller replaying a
+move that was already decided elsewhere (validated on a peer's machine, or
+authored) would let the two copies disagree about where the actor is if this
+re-judged it. Ask `canStep(dir)` first when you do want the map's opinion.
+`placeAt(x, y, facing)` snaps with no animation and clears any step in
+flight, for a warp arrival or a resync too far gone to walk off.
+`isMoving()` lets a driver pace itself instead of stomping a move already
+running. `setPassable(flag)` is the flag `Collision.occupied` skips (the
+engine's own user is Yellow's companion Pikachu); a passable object still
+draws and can still be talked to.
+
+An object spawned this way carries no `TEXT_*` id, so the vanilla talk path
+has nothing to say for it. The **`world.talk`** hook is the A press on an
+object, raised before the map's text tables get it:
+
+```lua
+mod.hooks:wrap("world.talk", function(next, ow, target)
+  if mine(target) then
+    say(target)        -- the mod answers for an object it owns
+    return             -- ...by not calling next()
+  end
+  return next(ow, target)   -- everything else falls through unchanged
+end)
+```
+
+With no subscriber the A press reaches `talkTo` exactly as before. An object
+mid-step raises no hook, matching the vanilla gate.
+
+## Adopting an already-paired link session
+
+`LinkState.newFromSession(game, transport, mode, isHost, opts)` starts a link
+session on a transport that is *already* paired, skipping the address/code
+entry UI while keeping the hello and fingerprint compatibility exchange
+intact. `transport` is anything `Session` accepts, which is what lets a mode
+tunnel a battle through its own connection rather than opening a second one.
+
+When the battle finishes, **`link.battle_ended`** reports the outcome:
+
+```lua
+mod.events:on("link.battle_ended", function(ev)
+  -- ev = { result, myParty, theirParty, peerName, role }
+end)
+```
+
+The party copies are the point. Cable rules leave the real party untouched,
+so a mode built on link battles -- a tournament ladder, a battle royale --
+has no other way to learn what the fight cost, and by the time the state
+unwinds the battle object is gone. `role` is `"host"` or `"guest"`.
+
+Two smaller pieces support the same shape of mode. `Game:startNewGame(opts)`
+is the title screen's NEW GAME closure made callable, with `opts.intro =
+false` to land straight in the world -- a mode that hands out its own starting
+state has no use for Oak's speech. `CodeEntry.new` takes an optional
+`{ length = , charset = }`, so the slot-scrub widget that enters a link code
+can also carry a room code or an address.
+
 ## Read-only battle snapshots
 
 `mod.battle:snapshot()` returns `nil` outside a battle and a copied battle
diff --git a/tests/modkit/cases/link_battle_ended.lua b/tests/modkit/cases/link_battle_ended.lua
new file mode 100644
index 00000000..93c5ff9c
--- /dev/null
+++ b/tests/modkit/cases/link_battle_ended.lua
@@ -0,0 +1,99 @@
+-- A sandboxed mod can read the outcome of a link battle -- who won, and the
+-- lockstep party copies -- through the public event surface.
+--
+-- The copies are the point.  Cable rules leave the real party untouched, so
+-- a mode built on link battles (a tournament ladder, a battle royale) has no
+-- other way to learn what the fight cost; by the time the state unwinds the
+-- battle object is gone.
+
+package.path = "./?.lua;./?/init.lua;" .. package.path
+love = love or require("tests.love_stub")
+
+local T = require("tests.modkit")
+local LinkState = require("src.link.LinkState")
+
+local FIXTURE = {
+  ["mods/outcome_probe/manifest.json"] = [[{
+    "id": "outcome_probe",
+    "name": "Outcome Probe",
+    "version": "1.0.0",
+    "entry": "main.lua",
+    "api": 2
+  }]],
+  ["mods/outcome_probe/main.lua"] = [[
+    local mod = ...
+    mod.exports.seen = 0
+    mod.events:on("link.battle_ended", function(ev)
+      mod.exports.seen = mod.exports.seen + 1
+      mod.exports.result = ev.result
+      mod.exports.role = ev.role
+      mod.exports.peerName = ev.peerName
+      mod.exports.myLead = ev.myParty and ev.myParty[1]
+      mod.exports.theirLead = ev.theirParty and ev.theirParty[1]
+    end)
+  ]],
+}
+
+-- a link session parked at the end of a battle: no transport, so update()
+-- goes straight to the stage that reports the outcome
+local function finishedSession(result, isHost)
+  local ls
+  ls = setmetatable({
+    stage = "battleRunning",
+    isHost = isHost,
+    peerName = "BLUE",
+    net = nil,
+    battle = {
+      result = result,
+      playerParty = { { species = "RATTATA", hp = 3 } },
+      enemyParty = { { species = "PIDGEY", hp = 0 } },
+    },
+    game = { input = {}, stack = { top = function() return ls end } },
+  }, { __index = LinkState })
+  -- the real exit unwinds the whole link stack; the event is what is under
+  -- test, so record the exit rather than run it
+  ls.exitWith = function() ls.exited = true end
+  return ls
+end
+
+-- ------- no mod: the battle still ends, nothing observes it
+
+local vanilla = T.sdk.loadNone({})
+local quiet = finishedSession("win", true)
+quiet:update(0)
+T.check(quiet.exited, "with no mod loaded the finished battle still unwinds")
+T.eq(quiet.battle, nil, "and lets go of the battle")
+vanilla.release()
+
+-- ------- a mod reads the outcome and both party copies
+
+local run = T.sdk.loadMods({ "mods/outcome_probe" }, { fs = T.sdk.memfs(FIXTURE) })
+T.eq(#run.errors, 0,
+  "the public outcome probe loads clean (" .. tostring(run.errors[1]) .. ")")
+
+local session = finishedSession("win", true)
+session:update(0)
+local out = run.loader.exports.outcome_probe or {}
+T.eq(out.seen, 1, "a finished link battle raises the event once")
+T.eq(out.result, "win", "the outcome is reported")
+T.eq(out.role, "host", "so is which side of the cable we were")
+T.eq(out.peerName, "BLUE", "and who we played")
+T.eq(out.myLead and out.myLead.species, "RATTATA",
+  "the lockstep copy of our party comes with it")
+T.eq(out.myLead and out.myLead.hp, 3,
+  "carrying the damage the real party never took")
+T.eq(out.theirLead and out.theirLead.species, "PIDGEY",
+  "and the copy of theirs")
+T.check(session.exited, "the state unwinds afterwards, as it always did")
+T.eq(session.battle, nil, "and the battle is released")
+
+-- the guest side says so
+local guest = finishedSession("lose", false)
+guest:update(0)
+T.eq(run.loader.exports.outcome_probe.seen, 2, "the guest reports too")
+T.eq(run.loader.exports.outcome_probe.role, "guest", "as the guest")
+T.eq(run.loader.exports.outcome_probe.result, "lose", "with its own outcome")
+
+run.release()
+
+T.finish("link_battle_ended")
diff --git a/tests/modkit/cases/world_talk.lua b/tests/modkit/cases/world_talk.lua
new file mode 100644
index 00000000..7ae3c73f
--- /dev/null
+++ b/tests/modkit/cases/world_talk.lua
@@ -0,0 +1,100 @@
+-- A sandboxed mod can claim the A press on an object it owns, using only
+-- public mod surfaces, and an unhooked build still talks to it as before.
+--
+-- The seam exists because a runtime object (WorldAPI:spawnNpc) carries no
+-- TEXT_* id: the vanilla talk path has nothing to say for one, so a mod that
+-- spawned it has to be able to answer instead.
+
+package.path = "./?.lua;./?/init.lua;" .. package.path
+love = love or require("tests.love_stub")
+
+local T = require("tests.modkit")
+local OverworldState = require("src.world.OverworldController")
+
+local FIXTURE = {
+  ["mods/talk_probe/manifest.json"] = [[{
+    "id": "talk_probe",
+    "name": "Talk Probe",
+    "version": "1.0.0",
+    "entry": "main.lua",
+    "api": 2
+  }]],
+  ["mods/talk_probe/main.lua"] = [[
+    local mod = ...
+    mod.hooks:wrap("world.talk", function(next, ow, target)
+      if target and target.claimedByMod then
+        mod.exports.claimed = target.id
+        return   -- deliberately not calling next(): the mod answers instead
+      end
+      return next(ow, target)
+    end)
+  ]],
+}
+
+-- enough of an overworld to reach the A press: a player facing one cell, an
+-- object standing on it, and a map with no counter to talk across
+local function fixtureOverworld(npc)
+  local ow
+  ow = setmetatable({
+    npcs = { npc },
+    player = {
+      facing = "up",
+      facingCell = function() return 4, 5 end,
+    },
+    map = {
+      id = "FIX_ROUTE",
+      isCounterCell = function() return false end,
+    },
+    talked = {},
+  }, { __index = OverworldState })
+  -- the vanilla destination, recorded rather than run: talkTo walks into the
+  -- map's text tables, which a fixture map does not have
+  ow.talkTo = function(_, target) ow.talked[#ow.talked + 1] = target.id end
+  return ow
+end
+
+local function objectAt(id, claimed)
+  return { id = id, cellX = 4, cellY = 5, targetX = 4, targetY = 5,
+           moving = false, claimedByMod = claimed or nil, def = {} }
+end
+
+-- ------- no mod: the A press lands in the vanilla talk path
+
+local vanilla = T.sdk.loadNone({})
+local plain = fixtureOverworld(objectAt("SIGNPOST_MAN"))
+plain:interact()
+T.eq(#plain.talked, 1, "with no mod loaded the A press reaches talkTo")
+T.eq(plain.talked[1], "SIGNPOST_MAN", "and it is handed the object it faced")
+vanilla.release()
+
+-- ------- a mod that owns the object answers for it
+
+local run = T.sdk.loadMods({ "mods/talk_probe" }, { fs = T.sdk.memfs(FIXTURE) })
+T.eq(#run.errors, 0,
+  "the public talk probe loads clean (" .. tostring(run.errors[1]) .. ")")
+
+local owned = fixtureOverworld(objectAt("GHOST_PLAYER", true))
+owned:interact()
+local out = run.loader.exports.talk_probe or {}
+T.eq(out.claimed, "GHOST_PLAYER", "a public hook sees the object it owns")
+T.eq(#owned.talked, 0,
+  "and a hook that does not call next keeps the vanilla text path out of it")
+
+-- ...while everything the mod does not own falls straight through
+local other = fixtureOverworld(objectAt("NURSE_JOY"))
+other:interact()
+T.eq(#other.talked, 1, "an object the mod does not claim still reaches talkTo")
+T.eq(other.talked[1], "NURSE_JOY", "unchanged")
+
+-- an object mid-step is not talkable in either build (walk_npc.asm), so the
+-- hook must not fire for one either
+local walking = fixtureOverworld(objectAt("WALKER", true))
+walking.npcs[1].moving = true
+walking:interact()
+T.eq(run.loader.exports.talk_probe.claimed, "GHOST_PLAYER",
+  "an object mid-step raises no talk hook")
+T.eq(#walking.talked, 0, "and reaches no talk path at all")
+
+run.release()
+
+T.finish("world_talk")