@jgengine/core 0.29.0 → 0.31.0

package/dist/ui/accessibility.d.ts

@@ -29,6 +29,14 @@ export declare function reducedMotionDuration(state: AccessibilityState, ms: num
  * maps to `null` (no filter). Consumed by the React `ColorblindFilters` defs.
  */
 export declare const COLORBLIND_MATRICES: Record<ColorblindMode, string | null>;
+/**
+ * The CSS filter that applies `mode` to one rendered frame — a `url(#jg-cb-<mode>)` reference to the
+ * `feColorMatrix` defs {@link COLORBLIND_MATRICES} drives. `"none"` maps to `null` (no filter), so a
+ * caller can spread it onto the canvas alone and leave HUD and menu text at its own contrast.
+ *
+ * @capability colorblind-frame-filter resolve a colorblind mode to the CSS filter for the 3D frame alone
+ */
+export declare function colorblindFrameFilter(mode: ColorblindMode): string | null;
 /** Observable, serializable accessibility-preferences store. */
 export interface AccessibilityStore {
     get(): AccessibilityState;

package/dist/ui/accessibility.js

@@ -32,6 +32,20 @@ export const COLORBLIND_MATRICES = {
     tritanopia: "0.95 0.05 0 0 0  0 0.433 0.567 0 0  0 0.475 0.525 0 0  0 0 0 1 0",
     grayscale: "0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0 0 0 1 0",
 };
+/**
+ * The CSS filter that applies `mode` to one rendered frame — a `url(#jg-cb-<mode>)` reference to the
+ * `feColorMatrix` defs {@link COLORBLIND_MATRICES} drives. `"none"` maps to `null` (no filter), so a
+ * caller can spread it onto the canvas alone and leave HUD and menu text at its own contrast.
+ *
+ * @capability colorblind-frame-filter resolve a colorblind mode to the CSS filter for the 3D frame alone
+ */
+export function colorblindFrameFilter(mode) {
+    const matrix = COLORBLIND_MATRICES[mode];
+    // An unknown id at runtime would reference a filter that does not exist, and a broken `url()` filter hides the element.
+    if (matrix === null || matrix === undefined)
+        return null;
+    return `url(#jg-cb-${mode})`;
+}
 /**
  * Serializable, observable store of accessibility preferences (reduced motion,
  * high contrast, text scale, colorblind mode, captions). Genre-agnostic plumbing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.29.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.31.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.29.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.31.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -728,7 +728,7 @@
 - `GameLoop` (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
 - `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: … — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
 - `HudCanvas` (function): function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: { layout: HudLayoutStore; editChord?: HudEditChord | false; /** Zoom applied to the whole HUD on compact displays. Default 0.85. */ compactScale?: number; /** Opt-in play-phase gate: render the HUD only … — Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine anchor regions and stack automatically with a gap — no per-panel pixel offsets, no manual clearance for sibling panels, the touch-control dock (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the whole surface scales down and each panel applies its `compact` behavior.
-- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
+- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
 - `PlayableGame` (type): type PlayableGame = EnginePlayableGame< ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps> > & { /** HUD theme the shell applies at the `GameUI` root. Unset uses `defaultHudTheme`; `false` opts out of the default theme and the en… — The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle.
 - `StatBar` (function): function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }: { statId?: string; entityId?: string; tone?: StatTone; label?: string; showValue?: boolean; width?: number; icon?: ReactNode; style?: CSSProperties; className?: string; }… — A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player). Renders nothing until the stat exists.
 - `StoreHandle` (interface): interface StoreHandle<T> — A typed, cast-free handle onto one slot of the reactive game store (`ctx.game.store`). The single type parameter is fixed at definition; `read`/`write`/`update` never widen to `unknown`, so no call site repeats `store.get(key) as T`. Writes flow through the engine store, so they bump `ctx.version()`, serialize into a {@link WorldSnapshot}, and replay under host authority — the same guarantees a hand-rolled `store.get`/`store.set` pair gives up the moment it forks run state into a module-level singleton.

package/skills/jgengine-gameplay/SKILL.md

@@ -44,7 +44,16 @@ tiers, manufacturer stat personalities and a level curve, all caller data.
 `validateLootItem` names each defect, `compareLootItems` returns per-stat deltas
 and a weighted score, and `lootWeaponDefinition` (`loot/lootWeapon`) projects a
 rolled item onto a `WeaponDefinition` for `createWeaponSystem`. `createLootRoller`
-counts drops per rarity for a debug probe and snapshots its counters. Sample
+counts drops per rarity for a debug probe and snapshots its counters.
+
+Roll a campaign drop with `rollDrop` (`loot/drop`) and show `compareToEquipped`
+against worn gear; carry and bank it with `createRunHaul` (`loot/haul`), which
+weighs the hold through the encumbrance rules and drops the hold on `fail`. Break
+an item down once with `salvageItem` and `createItemLedger` (`loot/salvage`), and
+price a vendor shelf through the wallet with `stockVendor` (`loot/vendor`).
+Bases and affixes take `minLevel`; bases take `mass`, which a roll carries forward.
+
+Sample
 catalog, distribution check and generated-weapon proof are in
 [reference-systems.md](reference-systems.md#procedural-gear).
 
@@ -121,6 +130,8 @@ Prefer `defineSystem` and `defineGame({ systems })` for scheduled capabilities.
 
 `createNearAgents` (`sim/nearAgents`) is the default near half: a nav crowd with a need set and a utility brain per agent, counting its decisions for tests and probes. Give it the same need definitions the off-screen world decays, or the two halves disagree at the boundary.
 
+`createAgent` (`agents/agent`) is one resident's whole life without the nav: needs decay through `sim/needs`, the utility brain picks among the targets the world offers, `agents/mood` reads a feeling from those needs plus named sources a queue or a litter patch raises, and an authored day plan (`agents/schedule`, which resolves `sim/routine`) puts the agent at work, at a meal or at home - including a work beat, where a stop names the places it patrols. A target that disappears falls to the agent's declared fallback. `createRelationshipBook` (`agents/relationships`) keeps familiarity and opinion per pair: a social action moves both, friends prefer each other's company, and a bonded pair refuses to split. Every part snapshots and restores. [Agent lives](recipes/agent-lives.md) wires both a park guest and a household being from the same factory.
+
 `createVisitorPopulation` (`sim/population`) is the crowd a scene reports, and it is the bodies: a visitor joins only when your `VisitorWorld.admit` has made its body, and only while `VisitorWorld.has` holds it, so `onSite()` is the member count a HUD reads in O(1) and `arrivalsToday()` is the sum of the admissions the world accepted rather than a tally kept beside them. Arrival rate, capacity (a number or a function of the clock), the leaving rule and the `inside` bounds check are game policy; a refused body or one placed outside the bounds is released and never counted. `rollDay()` closes the day without emptying the park, `adopt` takes over a body a save or a seed made, and a restore only brings back members the world still holds.
 
 Rides and their lines are `createRideSystem` and `createWaitQueue` (`sim/rides`, `sim/queue`): a ride cycles load → ride → unload at its own capacity, wears against its own breakdown curve, and reports boards, alights, breakdowns and repair costs through a sink; the wait a guest faces comes from the queue's own measured boarding throughput, not a configured constant. Guest choice stays on the utility brain — `rideChoiceOptions` compiles a guest's `RideTaste` (intensity comfort, nausea comfort, queue tolerance) and the park's ratings into options, `rideChoiceCandidates` costs each one by its own line's wait, and `createRideChooser` wires both to one guest. Ratings, cycle times, breakdown curves and costs are caller data, and `retune` changes them in play.

package/skills/jgengine-gameplay/api.md

@@ -2,6 +2,52 @@
 
 # jgengine-gameplay — exported API surface
 
+## @jgengine/core/agents/agent
+
+- `Agent` (interface): interface Agent — Needs, mood, schedule and a chosen action, in one object a game ticks.
+- `AgentAction` (interface): interface AgentAction — What the agent is doing.
+- `AgentActionReason` (type): type AgentActionReason = UtilitySwitchReason | "fallback" | "schedule" | "cleared" — Why the action last changed.
+- `AgentConfig` (interface): interface AgentConfig — Everything an agent is made of. Policy is data; nothing about a game is compiled in.
+- `AgentFallback` (interface): interface AgentFallback — Where an agent goes when the thing it wanted is gone: a named option and a named place.
+- `AgentFrame` (interface): interface AgentFrame — What one update produced: the action, the feeling, and where the day plan puts the agent.
+- `AgentSnapshot` (interface): interface AgentSnapshot — Serializable whole agent: needs, feeling, held action, day-plan cursor and the far flag.
+- `AgentTarget` (interface): interface AgentTarget — One reachable thing the agent could do this tick, as the game sees its own world.
+- `AgentUpdate` (interface): interface AgentUpdate — One call per tick: the clock, and the targets the game's world currently offers.
+- `createAgent` (function): function createAgent(config: AgentConfig): Agent — Create one agent. The same factory serves a park guest, a household being, a patrolling janitor and a soldier: `options` is what it can choose between, `schedule` is where its day puts it.
+
+## @jgengine/core/agents/mood
+
+- `DEFAULT_MOOD_TIERS` (const): const DEFAULT_MOOD_TIERS: readonly MoodTier[] — Five bands a park guest, a household being or a soldier can share. A game overrides them when its own tone needs different words; the numeric bands are what HUD counters and tests read.
+- `Mood` (interface): interface Mood — What the agent feels right now, on the caller's own tier labels.
+- `MoodReader` (interface): interface MoodReader — A mood reader that keeps the game-raised biases, so a queue or a litter patch moves mood too.
+- `MoodSnapshot` (interface): interface MoodSnapshot — Serializable mood state: the game-raised biases that sit on top of need satisfaction.
+- `MoodTier` (interface): interface MoodTier — One labelled band of the 0-100 mood score.
+- `MoodWeight` (interface): interface MoodWeight — One need's say in the mood score; weights are relative, so they need no fixed total.
+- `createMoodReader` (function): function createMoodReader(config: { readonly needs: Pick<NeedSet, "ids" | "fraction">; readonly weights?: readonly MoodWeight[]; readonly tiers?: readonly MoodTier[]; }): MoodReader — Create the mood an agent carries. Needs are the agent's own (shared with its utility brain), and every bias is named data the game can remove again - there is no decaying hidden penalty.
+- `moodTierOf` (function): function moodTierOf(score: number, tiers: readonly MoodTier[] = DEFAULT_MOOD_TIERS): MoodTier — The band a score reads as, from tiers sorted by `at` descending. Unknown or unsorted tiers fall back to the lowest declared band rather than throwing, because a HUD reads this every frame.
+- `readMood` (function): function readMood(needs: Pick<NeedSet, "ids" | "fraction">, weights: readonly MoodWeight[], tiers: readonly MoodTier[] = DEFAULT_MOOD_TIERS, sources?: Readonly<Record<string, number>>): Mood — A mood read from a need set: each declared need contributes its `0..1` satisfaction times its weight, normalized by the total weight, so an agent with four needs and one with six read on the same 0-100 scale. Pure and allocation-light - the per-frame read a HUD and a thought bubble share.
+
+## @jgengine/core/agents/relationships
+
+- `DEFAULT_RELATIONSHIP_MILESTONES` (const): const DEFAULT_RELATIONSHIP_MILESTONES: readonly RelationshipMilestone[] — The pair levels every game starts from; a game overrides the words and the cut points.
+- `DEFAULT_SOCIAL_CONTACT` (const): const DEFAULT_SOCIAL_CONTACT: Required<SocialContact> — What a plain social action adds: a shared moment nudges both dials, never maxes either.
+- `Relationship` (interface): interface Relationship — How one pair stands: how much time they have shared, and what they think of each other.
+- `RelationshipBook` (interface): interface RelationshipBook — Everyone's view of everyone else: familiarity and opinion per pair, changed by social actions, with the pair levels that make a friendship a preference and a bond a refusal to split.
+- `RelationshipBookSnapshot` (interface): interface RelationshipBookSnapshot — Serializable relationship state: every known pair plus the dials in play.
+- `RelationshipMilestone` (interface): interface RelationshipMilestone — One labelled bond level on the opinion scale.
+- `RelationshipPolicy` (interface): interface RelationshipPolicy — Tunables a game owns, every one reachable through {@link RelationshipBook.retune}.
+- `SocialContact` (interface): interface SocialContact — Opinion and familiarity one interaction adds; a game passes its own for a hug, a row or a shift.
+- `SocialOutcome` (interface): interface SocialOutcome — What one social action did to a pair.
+- `createRelationshipBook` (function): function createRelationshipBook(policy: RelationshipPolicy = {}): RelationshipBook — Create the shared book of pair state. Keys are undirected and delimiter-safe through `createPairKeyCodec`, and milestone crossings come from `crossThresholds`, so a notice feed and a journal both read the same event.
+
+## @jgengine/core/agents/schedule
+
+- `AgentSchedule` (interface): interface AgentSchedule — A day plan resolved against the world clock. No state to tick: a far agent reads the same day.
+- `AgentScheduleConfig` (interface): interface AgentScheduleConfig — An agent's whole day as data: what it does, where, and when.
+- `AgentSchedulePhase` (interface): interface AgentSchedulePhase — Where a schedule puts an agent at one instant.
+- `AgentScheduleStop` (interface): interface AgentScheduleStop extends RoutineStopSpec — One authored stop in an agent's day. The shape is the routine owner's (`sim/routine`) plus a beat: the places a working stop walks in order, so a janitor on patrol is an agent with a route rather than a special case.
+- `createAgentSchedule` (function): function createAgentSchedule(config: AgentScheduleConfig): AgentSchedule — Resolve an authored day plan into a clock-driven schedule. Timing, travel and arrival slips come from `sim/routine`; this adds the work beat and the refills a stop carries, so an off-hours stop is just another authored stop and a patrol is not a second scheduler.
+
 ## @jgengine/core/behaviour/behaviour
 
 - `Behaviour` (class): class Behaviour — Subclass and override the lifecycle hooks. A behaviour only joins the per-frame update dispatch if it actually overrides `onUpdate` (prototype-identity check at each activation), so hook-only behaviours cost nothing per frame.
@@ -1251,6 +1297,7 @@
 - `DEFAULT_ESCAPE_MULTIPLE` (const): const DEFAULT_ESCAPE_MULTIPLE: 3 — A pursuit escapes at this multiple of its keep-close distance when none is declared.
 - `DEFAULT_FIXED_STAGES` (const): const DEFAULT_FIXED_STAGES: readonly ["input", "movement", "combat", "ai", "activities", "cleanup"] — Default fixed-sim stage order — systems pick a stage; most need only this.
 - `DEFAULT_FRAME_STAGES` (const): const DEFAULT_FRAME_STAGES: readonly ["input", "movement", "combat", "ai", "activities", "cleanup", "animation", "camera", "effects"] — Default frame stage order. Gameplay stages mirror the fixed table so once-per-frame systems (`type: "frame"`) can pick `combat`/`ai`/… without falling into the unknown-stage bucket; presentation stages follow.
+- `DEFAULT_MARKER_TOLERANCE` (const): const DEFAULT_MARKER_TOLERANCE: 8 — Default vertical allowance (m) for a horizontal marker proximity test.
 - `DEFAULT_PICKUP_RADIUS` (const): const DEFAULT_PICKUP_RADIUS: 2 — ⚠ undocumented
 - `DEFAULT_PING_CATEGORIES` (const): const DEFAULT_PING_CATEGORIES: Record<PingCategory, PingCategoryDef> — Content-agnostic default ping wheel: enemy / loot / location / danger.
 - `DEFAULT_PURSUE_DISTANCE` (const): const DEFAULT_PURSUE_DISTANCE: 3 — Default keep-close distance (m) for a `pursue` objective.
@@ -1399,7 +1446,7 @@
 - `LootDropProvenance` (interface): interface LootDropProvenance — Why one drop is in the result: the stage/table/entry that produced it, its weights, and the modifiers that shaped it.
 - `LootFilterRule` (interface): interface LootFilterRule { id: string; when: LootFilterCondition; hide?: boolean; color?: string; beam?: boolean; label?: string } — ⚠ undocumented · used by `evaluateLootFilter`: First matching rule wins (PoE/Last Epoch block semantics) — later rules never override an earlier match.
 - `LootInstalledPart` (interface): interface LootInstalledPart — One part occupying one slot of a rolled item.
-- `LootIssueCode` (type): type LootIssueCode = | "invalid-level" | "unknown-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-finite-stat" | "empty-… — A defect found by {@link validateLootItem}.
+- `LootIssueCode` (type): type LootIssueCode = | "invalid-level" | "unknown-base" | "level-gated-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-f… — A defect found by {@link validateLootItem}.
 - `LootItem` (interface): interface LootItem — One rolled item: the base, maker, rarity, level, composed name, chosen parts, rolled affixes and resolved stats. Plain JSON, so a save stores it and the instance registry can key it.
 - `LootManufacturerDef` (interface): interface LootManufacturerDef — A maker with a stat personality: its mark goes in the name, `bias` shifts stats additively, `scale` multiplies them, and favored affix pools weigh more when this maker rolls the item.
 - `LootModifier` (interface): interface LootModifier<TCtx = unknown> — A registered, id-tagged loot policy applied to one stage. `plan` transforms eligibility, weights, and roll counts before rolling (luck, difficulty, gating); `drops` post-processes the rolled drops (quantity multipliers, dedupe, caps). Neither hook mutates table definitions, and the id is recorded in provenance so a resolved drop can be traced back to the policies that shaped it.
@@ -1447,6 +1494,8 @@
 - `MissionFailCondition` (interface): interface MissionFailCondition — A condition that fails the mission while the objective is active. `to` names a {@link MissionFailDef}; with no `to` the mission fails with the generic `"failed"` state.
 - `MissionFailDef` (interface): interface MissionFailDef — A named fail state an objective, timer or branch can land in.
 - `MissionIssue` (interface): interface MissionIssue — A located mission-catalog problem; `path` is a JSON Pointer into the supplied catalog.
+- `MissionMarkerPlane` (type): type MissionMarkerPlane = "horizontal" | "spatial" — Which plane a marker proximity test compares in.
+- `MissionMarkerProximity` (interface): interface MissionMarkerProximity — How a positional objective compares an actor to its authored marker.
 - `MissionObjectiveDef` (interface): interface MissionObjectiveDef — One objective. Every field is content; the machine reads only these.
 - `MissionObjectiveKind` (type): type MissionObjectiveKind = "reach" | "interact" | "survive" | "pursue" | "kill" | "collect" — The primitive goals an objective can have. Escort, chase and defend are not kinds — they are compositions of these plus fail conditions and timers (see `compositions.ts`).
 - `MissionRewardAppliers` (interface): interface MissionRewardAppliers — Appliers a mission reward routes through — the same shape quests use, plus a loot-table hook.
@@ -2132,7 +2181,7 @@
 
 ## @jgengine/core/item/affix
 
-- `AffixDef` (interface): interface AffixDef { id: string; stat: string; op?: AffixOp; roll: number | [number, number]; weight: number; namePart?: {position: "prefix" | "suffix"; text: string} } — ⚠ undocumented
+- `AffixDef` (interface): interface AffixDef { id: string; stat: string; op?: AffixOp; roll: number | [number, number]; weight: number; minLevel?: number; namePart?: {position: "prefix" | "suffix"; text: string} } — ⚠ undocumented
 - `AffixOp` (type): type AffixOp = "add" | "mul" — ⚠ undocumented
 - `AffixPool` (interface): interface AffixPool { id: string; affixes: readonly AffixDef[] } — ⚠ undocumented
 - `AffixRoller` (interface): interface AffixRoller { rollRarity(rng: () => number): RarityTier; roll(base: ItemBaseDef, rarityId: string, rng: () => number): RolledItem; rollRandom(base: ItemBaseDef, rng: () => number): RolledItem } — ⚠ undocumented · used by `createAffixRoller`: Rolls randomized gear from a base item: a weighted rarity tier scales base stats and picks prefix/suffix affixes that name and modify the it…
@@ -2263,6 +2312,25 @@
 - `createWeaponStats` (function): function createWeaponStats(resolveEntry: (itemId: string) => WeaponEntry | null | undefined): WeaponStats — Resolve per-weapon stat values — damage, fire rate, spread — for combat math.
 - `getWeaponStat` (function): function getWeaponStat(entry: WeaponEntry | null | undefined, stat: string): number | null — ⚠ undocumented
 
+## @jgengine/core/loot/drop
+
+- `EquippedComparison` (interface): interface EquippedComparison — What a HUD renders when a drop lands: per-stat deltas against the worn item and one verdict.
+- `EquippedStatDelta` (interface): interface EquippedStatDelta extends LootStatDelta — A per-stat delta from the equipped item to the candidate; positive `delta` means the candidate is larger.
+- `ItemDrop` (interface): interface ItemDrop extends LootItem — A rolled item with a stable instance id, so a stash, ledger and vendor stock can name it.
+- `RollDropOptions` (interface): interface RollDropOptions extends LootRollOptions — {@link rollDrop} options: the loot roll plus the instance id (defaults to `drop:<seed>`).
+- `compareToEquipped` (function): function compareToEquipped(candidate: ItemDrop, equipped: ItemDrop | null, options: LootComparisonOptions = {}): EquippedComparison — Compare a dropped item against what is equipped, with one delta per stat and a weighted verdict. The delta is `candidate - equipped`; `better` flips for stats the caller lists in `lowerIsBetter`, so reload time improving does not read as worse. A missing equipped item compares against zeros.
+- `itemMass` (function): function itemMass(item: Pick<LootItem, "mass">): number — Carried mass of a rolled item. Older saves may predate `mass`; those default to `1`.
+- `rollDrop` (function): function rollDrop(catalog: LootCatalog, seed: string | number, options: RollDropOptions = {}): ItemDrop — Roll one item from a seed. Same seed, catalog and options produce the same id, name, affixes, stats and mass on every run; level gates which bases and affixes are in the pool.
+
+## @jgengine/core/loot/haul
+
+- `CarryOutcome` (type): type CarryOutcome = | { ok: true; mass: number; remaining: number } | { ok: false; reason: "over-capacity" | "no-space" | "invalid-count"; mass: number; remaining: number } — What a carry attempt returns: the new load, or the rule that refused it.
+- `HaulTransfer` (interface): interface HaulTransfer — Stacks moved between a run and its stash, or lost when the run fails.
+- `RunHaul` (interface): interface RunHaul — A run's carried loot and the stash that outlives it.
+- `RunHaulConfig` (interface): interface RunHaulConfig<TId extends string> — What a run haul needs: two inventories, a weight rule and an optional save cell.
+- `RunHaulState` (interface): interface RunHaulState — Detached run and stash contents, for a save or a debug readout.
+- `createRunHaul` (function): function createRunHaul<TId extends string>(config: RunHaulConfig<TId>): RunHaul — A run's haul beside a persistent stash. Carrying is gated by the shared encumbrance rules; `bank` moves what the stash fits and saves; `fail` throws the run's haul away and leaves the stash as it was. The game decides when a run succeeds or fails and calls one of them.
+
 ## @jgengine/core/loot/lootGen
 
 - `LootBaseDef` (interface): interface LootBaseDef extends ItemBaseDef — A base family (frame, housing, chassis — caller nouns) with its slots, stats and affix pools.
@@ -2270,7 +2338,7 @@
 - `LootComparison` (interface): interface LootComparison — How two items compare: every stat delta plus one weighted score for each.
 - `LootComparisonOptions` (interface): interface LootComparisonOptions — Caller policy for the comparison score.
 - `LootInstalledPart` (interface): interface LootInstalledPart — One part occupying one slot of a rolled item.
-- `LootIssueCode` (type): type LootIssueCode = | "invalid-level" | "unknown-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-finite-stat" | "empty-… — A defect found by {@link validateLootItem}.
+- `LootIssueCode` (type): type LootIssueCode = | "invalid-level" | "unknown-base" | "level-gated-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-f… — A defect found by {@link validateLootItem}.
 - `LootItem` (interface): interface LootItem — One rolled item: the base, maker, rarity, level, composed name, chosen parts, rolled affixes and resolved stats. Plain JSON, so a save stores it and the instance registry can key it.
 - `LootManufacturerDef` (interface): interface LootManufacturerDef — A maker with a stat personality: its mark goes in the name, `bias` shifts stats additively, `scale` multiplies them, and favored affix pools weigh more when this maker rolls the item.
 - `LootPartDef` (interface): interface LootPartDef extends PartDef — A part a base can mount: its stats, a pick weight, and an optional word for the item name.
@@ -2296,6 +2364,30 @@
 - `LootWeaponStatMap` (interface): interface LootWeaponStatMap — Which rolled stat feeds which part of a {@link WeaponDefinition}. Every field is a stat id from the item; an omitted field keeps the template's value, so a catalog only maps what it rolls.
 - `lootWeaponDefinition` (function): function lootWeaponDefinition(item: LootItem, projection: LootWeaponProjection): WeaponDefinition — Project a rolled item onto a plain weapon definition: copy the template, then write the mapped stats into rate, damage, magazine, spread, range and projectile speed. The result is a {@link WeaponDefinition}, so `assertWeaponDefinition` and `createWeaponSystem` accept it unchanged.
 
+## @jgengine/core/loot/salvage
+
+- `ItemDropLike` (interface): interface ItemDropLike — The fields salvage reads; an `ItemDrop` from `./drop` satisfies it.
+- `ItemLedger` (interface): interface ItemLedger — One record of what happened to rolled item instances. Every path that removes an item - salvage, sale, granting a duplicate - claims it here first, so a second claim returns false and the item cannot be equipped, sold or broken down twice.
+- `ItemLedgerState` (type): type ItemLedgerState = Readonly<Record<string, Exclude<ItemLifecycle, "owned">>> — Items that have left play, keyed by instance id; anything absent is still `owned`.
+- `ItemLifecycle` (type): type ItemLifecycle = "owned" | "salvaged" | "sold" — Where an item instance stands: still usable, broken down, or sold.
+- `SalvageResult` (type): type SalvageResult = | { ok: true; id: string; yield: SalvageYield } | { ok: false; reason: "already-spent" | "invalid-item" } — Salvage outcome: the yield, or the reason the instance could not be broken down.
+- `SalvageTable` (interface): interface SalvageTable — What a broken-down item is worth: a game-authored currency, rate and per-rarity multiplier.
+- `SalvageYield` (interface): interface SalvageYield — The currency and amount one salvage yields. `currency` is the game's key, never interpreted.
+- `createItemLedger` (function): function createItemLedger(initial: ItemLedgerState = {}): ItemLedger — Build an item ledger. Ids are consumed once: the first successful {@link ItemLedger.spend} wins, every later call fails, which is what makes salvage and sale mutually exclusive.
+- `salvageItem` (function): function salvageItem(item: ItemDropLike, table: SalvageTable, ledger: ItemLedger): SalvageResult — Break one item down through its ledger. The ledger is claimed before the yield is computed, so a salvaged item cannot be salvaged, equipped or sold again; pass the game's own wallet update from `yield`.
+- `salvageValue` (function): function salvageValue(item: Pick<ItemDropLike, "level" | "rarity">, table: SalvageTable): SalvageYield — The yield an item of this level and rarity breaks down into. The formula is `round(perLevel x level x rarityMultiplier)`, floored by `minimum`, so the same item always yields the same amount and a higher level never yields less.
+
+## @jgengine/core/loot/vendor
+
+- `StockVendorOptions` (interface): interface StockVendorOptions — What stocking a vendor reads: the roll catalog, a seeded rng and the pricing policy.
+- `VendorOffer` (interface): interface VendorOffer — One stocked item and the shop entry that prices it.
+- `VendorPriceRule` (interface): interface VendorPriceRule — How a vendor price is derived from an item: a base, a per-level rate and a rarity multiplier.
+- `VendorRotation` (interface): interface VendorRotation — A run-count refresh rule; the game owns how many runs between restocks.
+- `VendorRotationState` (interface): interface VendorRotationState — Where a vendor shelf stands: the run number it was last stocked on.
+- `createVendorRotation` (function): function createVendorRotation(everyRuns: number, start = 0): VendorRotation — A restock rule the game authors as "every N runs". It only answers when a refresh is due; the game calls {@link stockVendor} and then `mark`. No timer, so a paused or reloaded save keeps the same shelf until the run count moves.
+- `itemPrice` (function): function itemPrice(item: Pick<LootItem, "level" | "rarity">, rule: VendorPriceRule): { buy: number; sell: number | null } — The price of one item under a `VendorPriceRule`: `round(base + perLevel x level)` times the rarity multiplier, never below 1. Sell-back is `floor(price x sellFactor)` when the rule sets one.
+- `stockVendor` (function): function stockVendor(shop: ShopStock, options: StockVendorOptions): VendorOffer[] — Roll a vendor's shelf and add it to an existing {@link ShopStock}. Entries added by a previous call with the same `idPrefix` are removed first, so a refresh replaces the shelf instead of throwing on duplicate ids. Buying, selling and wallet charging stay in the economy owner.
+
 ## @jgengine/core/mission/compositions
 
 - `ChaseMissionOptions` (interface): interface ChaseMissionOptions extends ComposedMissionOptions — Options for {@link chaseMission}: a target kept close until it is caught.
@@ -2309,6 +2401,7 @@
 ## @jgengine/core/mission/mission
 
 - `DEFAULT_ESCAPE_MULTIPLE` (const): const DEFAULT_ESCAPE_MULTIPLE: 3 — A pursuit escapes at this multiple of its keep-close distance when none is declared.
+- `DEFAULT_MARKER_TOLERANCE` (const): const DEFAULT_MARKER_TOLERANCE: 8 — Default vertical allowance (m) for a horizontal marker proximity test.
 - `DEFAULT_PURSUE_DISTANCE` (const): const DEFAULT_PURSUE_DISTANCE: 3 — Default keep-close distance (m) for a `pursue` objective.
 - `DEFAULT_REACH_RADIUS` (const): const DEFAULT_REACH_RADIUS: 2.5 — Default proximity radius (m) for a `reach` / `interact` objective.
 - `MISSION_COUNTER_KINDS` (const): const MISSION_COUNTER_KINDS: readonly MissionObjectiveKind[] — Objective kinds that are satisfied only by a counter — a mission made of these alone is a lint error.
@@ -2321,6 +2414,8 @@
 - `MissionFailCondition` (interface): interface MissionFailCondition — A condition that fails the mission while the objective is active. `to` names a {@link MissionFailDef}; with no `to` the mission fails with the generic `"failed"` state.
 - `MissionFailDef` (interface): interface MissionFailDef — A named fail state an objective, timer or branch can land in.
 - `MissionIssue` (interface): interface MissionIssue — A located mission-catalog problem; `path` is a JSON Pointer into the supplied catalog.
+- `MissionMarkerPlane` (type): type MissionMarkerPlane = "horizontal" | "spatial" — Which plane a marker proximity test compares in.
+- `MissionMarkerProximity` (interface): interface MissionMarkerProximity — How a positional objective compares an actor to its authored marker.
 - `MissionObjectiveDef` (interface): interface MissionObjectiveDef — One objective. Every field is content; the machine reads only these.
 - `MissionObjectiveKind` (type): type MissionObjectiveKind = "reach" | "interact" | "survive" | "pursue" | "kill" | "collect" — The primitive goals an objective can have. Escort, chase and defend are not kinds — they are compositions of these plus fail conditions and timers (see `compositions.ts`).
 - `MissionRewardAppliers` (interface): interface MissionRewardAppliers — Appliers a mission reward routes through — the same shape quests use, plus a loot-table hook.
@@ -2349,6 +2444,26 @@
 - `missionMarkers` (function): function missionMarkers(document: SceneDocumentLike): Record<string, ScenePoint3> — Marker positions from an authored scene, keyed by marker id — what a positional objective reads.
 - `registerMissionTriggerActions` (function): function registerMissionTriggerActions(): void — Register {@link MISSION_TRIGGER_ACTIONS} so the editor lists them. Idempotent; call at module load next to the game's catalogs.
 
+## @jgengine/core/progression/careerBank
+
+- `CareerBank` (interface): interface CareerBank — Persistent career money plus the run in progress, which a failed run loses.
+- `CareerBankConfig` (interface): interface CareerBankConfig — Configuration for {@link createCareerBank}.
+- `CareerBankState` (interface): interface CareerBankState — Everything a career bank stores, as plain JSON. `banked` is the persistent balance; `haul` is the run in progress and is the part a failed run loses. `deposited`, `lost`, `bestHaul` and `runs` are lifetime counters a results screen reads.
+- `createCareerBank` (function): function createCareerBank(config: CareerBankConfig): CareerBank — Money that means something between runs: a persistent balance plus a run's haul that is banked on a cash-out and lost on a failure. Amounts are snapped to the currency's minor units, so a save round-trip and a display never drift. Pair it with `economy/upgrades` for a career upgrade tree.
+
+## @jgengine/core/progression/gates
+
+- `GateDef` (interface): interface GateDef — A milestone: content that opens exactly when its requirements hold and names the unlock it grants. `unlock` must resolve in the catalog the set is built with, or the set refuses to load.
+- `GateFacts` (interface): interface GateFacts — What a gate is evaluated against: standing by track and money by currency.
+- `GateMiss` (type): type GateMiss = "standing" | "balance" — Which named condition a closed gate still needs.
+- `GateRequirement` (interface): interface GateRequirement — Every condition a gate can require; all named conditions must hold.
+- `GateSet` (interface): interface GateSet — Evaluated gate content: the table, its status against facts, and the grants a caller applies.
+- `GateSetConfig` (interface): interface GateSetConfig — Content and the resolvers a {@link GateSet} is built from.
+- `GateStatus` (interface): interface GateStatus — One gate against live facts.
+- `assertGates` (function): function assertGates(config: GateSetConfig): void — Check an authored gate table against the content it grants; throws `RangeError` naming the gate.
+- `createGateSet` (function): function createGateSet(config: GateSetConfig): GateSet — Authored unlock gates: each one names the unlock it grants and the standing or balance it reads. Evaluated against caller-supplied facts, so one table serves a single-player save, a server actor or a probe. Load refuses a gate whose unlock id resolves to nothing (the D3.8 class), so a dead milestone fails at startup instead of in play. A gate with no requirements is open from the start.
+- `gateFacts` (function): function gateFacts(standing: Pick<Standing, "standing">, actorId: string, balances: Readonly<Record<string, number>> = {}): GateFacts — Read a {@link Standing} and a balance record as {@link GateFacts}.
+
 ## @jgengine/core/progression/gearScore
 
 - `GearScore` (interface): interface GearScore — A scored loadout: the total, each slot's share, each stat's signed contribution, and how complete it is.
@@ -2372,6 +2487,18 @@
 - `assertSkillTreeConfig` (function): function assertSkillTreeConfig<TStat extends string>(config: SkillTreeConfig<TStat>): void — Check tree data before play; throws `RangeError` naming the offending node, requirement or synergy.
 - `createSkillTree` (function): function createSkillTree<TStat extends string = string>(config: SkillTreeConfig<TStat>, options: { devtoolsName?: string } = {}): SkillTree<TStat> — A data-authored skill tree: nodes carry a point cost, prerequisites, passives and unlocked actions, synergies pay off two or more nodes together, and `respec` refunds exactly the points spent. Spend against `canSpend` for a reason a UI can show; read `resolved()` for the stat modifiers and action list to feed `createStats` / `createAbilityKit`.
 
+## @jgengine/core/progression/standing
+
+- `Standing` (interface): interface Standing — Live standing over authored tracks, moved by named outcomes or direct adjustments, with the tier on each track and a serializable snapshot.
+- `StandingChange` (interface): interface StandingChange — One track's movement, with the tier on both sides so a caller can announce a crossing.
+- `StandingConfig` (interface): interface StandingConfig — Authored standing content: the tracks an actor stands with, and the outcomes that move them.
+- `StandingOutcomeDef` (interface): interface StandingOutcomeDef — One outcome a game can report, and the standing it moves on each track.
+- `StandingRequirement` (interface): interface StandingRequirement — A threshold on one track, as an unlock or an upgrade reads it.
+- `StandingState` (interface): interface StandingState — Plain JSON state of a {@link Standing}; tracks left at their authored `initial` are absent.
+- `StandingTrackDef` (interface): interface StandingTrackDef — One standing track: a faction, a district, a licence board — whatever an authored outcome moves.
+- `assertStandingConfig` (function): function assertStandingConfig(config: StandingConfig): void — Check authored standing content before use; throws `RangeError` naming the offending field.
+- `createStanding` (function): function createStanding(config: StandingConfig): Standing — Per-faction or per-district standing that rises and falls from named outcomes, over authored tracks. Numbers live in the shared reputation ledger (`faction/reputation`); this adds the authored outcome table, tier-per-track and the one snapshot a save stores. An outcome id or track id that resolves to nothing throws at the call, so authored content fails loudly.
+
 ## @jgengine/core/progression/statGraph
 
 - `StatContribution` (interface): interface StatContribution — One folded contribution to a value, retained so a sheet can explain "why is this value 42?" — every step carries the source that produced it.
@@ -2389,6 +2516,17 @@
 - `createStatGraph` (function): function createStatGraph(def: StatGraphDef): StatGraph — A data-driven stat graph: game-owned named inputs feed caller-authored derived formulas, with contribution provenance, uncommitted previews, cycle detection, and selective recomputation. Formula semantics and numeric tables stay entirely game-defined.
 - `statModifierContributions` (function): function statModifierContributions<TStat extends string>(source: string, set: StatModifierSet<TStat>): Record<string, StatContribution[]> — Bridge the shared {@link StatModifierSet} shape (add/multiply, used by talents, items, and buffs) into stat-graph contributions, so a ranked talent tree or gear roll feeds the graph as one named source instead of a parallel store.
 
+## @jgengine/core/progression/upgrades
+
+- `UpgradeBuy` (type): type UpgradeBuy = { ok: true; nodeId: string; rank: number; cost: number } | { ok: false; reason: UpgradeRejection } — Result of {@link UpgradeTree.buy}: the rank reached and what it cost, or why it was refused.
+- `UpgradeNodeDef` (interface): interface UpgradeNodeDef — One upgrade node. Its price is the shared progression {@link Curve} evaluated at the rank being bought, so a game authors one curve and every rank of every node follows it.
+- `UpgradeRejection` (type): type UpgradeRejection = "unknown-node" | "max-rank" | "missing-prerequisites" | "standing" | "insufficient-funds" — Why a purchase was refused; the tree is left untouched on any rejection.
+- `UpgradeState` (interface): interface UpgradeState — Plain JSON state: node id → ranks owned. Nodes at rank `0` are absent.
+- `UpgradeTree` (interface): interface UpgradeTree — Authored upgrade nodes with a per-node cost curve, prerequisites, a standing gate and one snapshot.
+- `UpgradeTreeConfig` (interface): interface UpgradeTreeConfig — Authored nodes plus the standing a node's requirement reads.
+- `assertUpgrades` (function): function assertUpgrades(config: UpgradeTreeConfig): void — Check authored upgrade nodes; throws `RangeError` naming the offending node or field.
+- `createUpgradeTree` (function): function createUpgradeTree(config: UpgradeTreeConfig): UpgradeTree — An upgrade tree whose prices come from the shared curve primitive: each node authors one cost curve, each rank is that curve at the rank, and a purchase passes prerequisites, a standing gate and the caller's own payment step. State is one rank map that JSON round-trips, so a career save stores what a player paid for rather than the arithmetic behind it.
+
 ## @jgengine/core/progression/xpCurve
 
 - `XpCurve` (interface): interface XpCurve — A resolved, validated {@link XpCurveDef}: thresholds, lifetime totals, a stated rule, and a leveling track bound to the same numbers.

package/skills/jgengine-gameplay/capabilities.md

@@ -16,6 +16,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createAffixRoller` (function) · `import { createAffixRoller } from "@jgengine/core/gameplay"`
 
+## agent-schedule — an authored per-agent day plan with a work beat and off-hours behaviour
+
+- `createAgentSchedule` (function) · `import { createAgentSchedule } from "@jgengine/core/agents/schedule"`
+
+## agents — a needs, thought, action and mood loop an agent runs on the world clock
+
+- `createAgent` (function) · `import { createAgent } from "@jgengine/core/agents/agent"`
+
 ## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
 
 - `createAuctionBook` (function) · `import { createAuctionBook } from "@jgengine/core/gameplay"`
@@ -36,6 +44,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `cancelJob` (function) · `import { cancelJob } from "@jgengine/core/gameplay"`
 
+## career-bank — persistent career money with a run haul that can be banked or lost
+
+- `createCareerBank` (function) · `import { createCareerBank } from "@jgengine/core/progression/careerBank"`
+
 ## carry-encumbrance — gate a pickup against the carrier's remaining capacity
 
 - `canCarry` (function) · `import { canCarry } from "@jgengine/core/inventory/carryLoad"`
@@ -232,6 +244,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `splitStack` (function) · `import { splitStack } from "@jgengine/core/inventory/inventoryModel"`
 
+## item-comparison — show per-stat deltas and a weighted verdict for a drop against equipped gear
+
+- `compareToEquipped` (function) · `import { compareToEquipped } from "@jgengine/core/loot/drop"`
+
 ## item-generation — compose constraints, weighted pools, transforms, and provenance into a deterministic generated item
 
 - `generate` (function) · `import { generate } from "@jgengine/core/gameplay"`
@@ -253,10 +269,46 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `createItemInstanceRegistry` (function) · `import { createItemInstanceRegistry } from "@jgengine/core/gameplay"`
 - `proceduralLootEntry` (function) · `import { proceduralLootEntry } from "@jgengine/core/gameplay"`
 
+## item-ledger — track which rolled item instances are still owned, salvaged or sold
+
+- `createItemLedger` (function) · `import { createItemLedger } from "@jgengine/core/loot/salvage"`
+
+## item-roll — roll one deterministic, level-gated item from a seed
+
+- `rollDrop` (function) · `import { rollDrop } from "@jgengine/core/loot/drop"`
+
+## item-run-haul — carry loot with a weight gate, bank it into a persistent stash, or lose it when the run fails
+
+- `createRunHaul` (function) · `import { createRunHaul } from "@jgengine/core/loot/haul"`
+
+## item-salvage — break an item down for the currency its level and rarity say, once
+
+- `salvageItem` (function) · `import { salvageItem } from "@jgengine/core/loot/salvage"`
+
+## item-salvage-value — compute the currency an item of a level and rarity breaks down into
+
+- `salvageValue` (function) · `import { salvageValue } from "@jgengine/core/loot/salvage"`
+
 ## item-use-composition — compose pluggable, ordered item use-behaviors from serializable references
 
 - `createUseBehaviorRegistry` (function) · `import { createUseBehaviorRegistry } from "@jgengine/core/gameplay"`
 
+## item-vendor — stock a vendor with rolled items priced through the shared economy
+
+- `stockVendor` (function) · `import { stockVendor } from "@jgengine/core/loot/vendor"`
+
+## item-vendor-price — price an item from its level and rarity through the economy's currency
+
+- `itemPrice` (function) · `import { itemPrice } from "@jgengine/core/loot/vendor"`
+
+## item-vendor-rotation — decide when a vendor's shelf is due for a restock
+
+- `createVendorRotation` (function) · `import { createVendorRotation } from "@jgengine/core/loot/vendor"`
+
+## item-weight — read a rolled item's mass for a carry check
+
+- `itemMass` (function) · `import { itemMass } from "@jgengine/core/loot/drop"`
+
 ## key-rebinding — conflict-aware key-remap session over the action-binding model — capture/reassign, conflict detection, reset-to-defaults, persist overrides, snapshot/restore
 
 - `createRebindSession` (function) · `import { createRebindSession } from "@jgengine/core/gameplay"`
@@ -392,6 +444,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `slotAccepts` (function) · `import { slotAccepts } from "@jgengine/core/gameplay"`
 
+## mood — a mood derived from how satisfied an agent's needs are
+
+- `createMoodReader` (function) · `import { createMoodReader } from "@jgengine/core/agents/mood"`
+- `moodTierOf` (function) · `import { moodTierOf } from "@jgengine/core/agents/mood"`
+- `readMood` (function) · `import { readMood } from "@jgengine/core/agents/mood"`
+
 ## move — a keyed value toward a target by a bounded step
 
 - `towardValue` (function) · `import { towardValue } from "@jgengine/core/gameplay"`
@@ -537,6 +595,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `attachRefusalNotices` (function) · `import { attachRefusalNotices } from "@jgengine/core/game/notices"`
 
+## relationships — familiarity and opinion between agents, with a bond that changes behaviour
+
+- `createRelationshipBook` (function) · `import { createRelationshipBook } from "@jgengine/core/agents/relationships"`
+
 ## resolve — the current tier/band label for a keyed or scalar value
 
 - `tierAt` (function) · `import { tierAt } from "@jgengine/core/gameplay"`
@@ -651,6 +713,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `stationOutputRate` (function) · `import { stationOutputRate } from "@jgengine/core/gameplay"`
 
+## standing — per-track standing moved by authored outcomes, with tiers and one snapshot
+
+- `createStanding` (function) · `import { createStanding } from "@jgengine/core/progression/standing"`
+
 ## stat-graph — derive game-defined stats from named inputs with provenance and preview
 
 - `createStatGraph` (function) · `import { createStatGraph } from "@jgengine/core/gameplay"`
@@ -724,6 +790,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `unitTrainingConfig` (function) · `import { unitTrainingConfig } from "@jgengine/core/gameplay"`
 
+## unlock-gates — milestones gated by standing or money, validated against the content they grant
+
+- `createGateSet` (function) · `import { createGateSet } from "@jgengine/core/progression/gates"`
+
 ## unlock-points — spendable point pool earned per level and spent to unlock nodes, with refund and respec
 
 - `createUnlockPoints` (function) · `import { createUnlockPoints } from "@jgengine/core/economy/unlockPoints"`
@@ -732,6 +802,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createUnlockCatalog` (function) · `import { createUnlockCatalog } from "@jgengine/core/gameplay"`
 
+## upgrade-tree — ranked upgrades priced by a cost curve, gated by prerequisites and standing
+
+- `createUpgradeTree` (function) · `import { createUpgradeTree } from "@jgengine/core/progression/upgrades"`
+
 ## visitor-population — a crowd whose on-site and daily counts are the bodies the game made
 
 - `createVisitorPopulation` (function) · `import { createVisitorPopulation } from "@jgengine/core/gameplay"`

package/skills/jgengine-gameplay/recipes/agent-lives.md

@@ -0,0 +1,76 @@
+# Agent lives: needs, mood, relationships, schedules
+
+One system for every resident that wants something. `createAgent` (`@jgengine/core/agents/agent`)
+composes four owners that already exist: `createNeedSet` (`sim/needs`) decays the needs,
+`createUtilityBrain` (`ai/utilityBrain`) scores what to do, `resolveRoutine` (`sim/routine`) says
+where the day plan puts the agent, and `createMoodReader` (`agents/mood`) reads how satisfied it is.
+A game supplies the targets its world offers and owns the body, the nav and the art.
+
+```ts
+import { createAgent } from "@jgengine/core/agents/agent";
+import { createRelationshipBook } from "@jgengine/core/agents/relationships";
+
+const needs = [
+  { id: "hunger", max: 100, rate: 0.9 },
+  { id: "fun", max: 100, rate: 0.6 },
+  { id: "energy", max: 100, rate: 0.5 },
+];
+
+const agent = createAgent({
+  id: "guest:1",
+  needs,
+  options: [
+    { id: "eat", terms: [{ need: "hunger", curve: { kind: "linear", from: 0.2, to: 0.95 } }] },
+    { id: "ride", terms: [{ need: "fun", curve: { kind: "linear", from: 0.15, to: 0.9 } }] },
+    { id: "seat", base: 0.05, terms: [{ need: "energy", curve: { kind: "linear", from: 0.1, to: 1 } }] },
+    { id: "work", base: 0.2 },
+  ],
+  schedule: {
+    cycleSeconds: 86_400,
+    stops: [
+      { place: "home", arriveAt: 0, activity: "sleep", refill: { energy: 70 } },
+      { place: "lobby", arriveAt: 30_000, activity: "work", beat: ["hall-a", "hall-b", "hall-c"] },
+      { place: "cafe", arriveAt: 50_000, activity: "meal", refill: { hunger: 60 } },
+    ],
+    travelSeconds: (from, to) => distances.get(`${from}>${to}`) ?? 60,
+  },
+  mood: { weights: [{ need: "hunger", weight: 2 }, { need: "fun", weight: 1 }] },
+  rng: ctx.rng,
+});
+
+agent.update({
+  dt,
+  now: ctx.time.now(),
+  targets: [
+    { option: "ride", target: "coaster", cost: queueSeconds, fallback: { option: "seat", target: "bench" } },
+    { option: "eat", target: "burger-stall", cost: walkSeconds },
+    { option: "seat", target: "bench" },
+  ],
+});
+```
+
+Read the frame, not the internals: `frame.action` (`option`, `target`, `usedFallback`), `frame.mood`
+(`score`, `tier`, `label`), `frame.phase` and `frame.post` (where the schedule and the work beat put
+the agent), and `frame.changed` with `frame.reason`. `targets` is the world as it is this tick, so a
+sold-out stall simply is not in the list, and a pick whose target disappears moves to its declared
+`fallback` instead of freezing.
+
+- **Saved state.** `agent.snapshot()` carries needs (values, rates, modifiers), mood sources, the held
+  pick and its dials, the action, the far flag and the schedule stop the agent last ate at. The day
+  plan itself is authored data resolved from the clock, so it is never saved. Put every agent's
+  snapshot and one `book.snapshot()` in the save document.
+- **Far agents.** `agent.setFar(true)` stops the utility pass: the agent keeps decaying and follows
+  its schedule, and its action reads off the phase. A far agent costs no decision and no nav.
+- **Mood from the world.** `agent.moodSources.setSource("queue", -20)` and `clearSource` let a queue,
+  litter, a broken ride or a cold snap move the feeling without giving mood its own state machine.
+- **One relationship book per world.** `book.socialise(a, b, { opinion: 6, familiarity: 0.1 })` returns
+  the pair before and after plus the milestones crossed. `book.prefersCompanyOf(a, b)` is a friendship
+  a game can act on by seating them together; `book.refusesToSplit(a, b)` is a bond that must not be
+  posted to separate shifts. A bond needs opinion *and* time shared, so one good afternoon is not
+  enough.
+- **A work beat is not a special case.** A stop with `beat` walks those places in order for
+  `beatDwellSeconds` each; a janitor, a security guard and a tour guide are the same agent with
+  different authored beats. Off-hours behaviour is a stop without a beat.
+- **Determinism.** Pass `ctx.rng` and set `jitter`; two agents built from the same seeded stream make
+  the same choices. The game owns the RNG cursor in its save (`createGameSave` `rng`), since one
+  stream is usually shared by the whole world.