Player-facing wiki rewrite

2026-07-16 02:19:03 +00:00
parent 118c55c47d
commit bf6825519c
12 changed files with 1043 additions and 796 deletions
@@ -0,0 +1,116 @@
 # Compatibility
 *Contraband adds its own content and reads from the base game rather than rewriting it. That is why it
 composes with other mods instead of colliding with them.*
 ## Requires: Institution: Core
 Contraband has a hard dependency on **Institution: Core** and loads after it. This is not optional —
 after the split, everything Contraband reads lives in Core:
 | Core provides | Contraband uses it for |
 |---|---|
 | Which pawns count as "in custody," and who can hide things | who counts as a concealer; who can be intaken, whittle, or dig |
 | A pawn's criminal propensity (nature × nurture) | every disposition roll — intake (0.6), improvise (0.10), dig (0.08), all scaled and settled per pawn |
 | The criminal record | times searched, times caught, escape attempts, contraband made — written by search and acquisition, read by search priority |
 Install Contraband without Core and it will not run. Everything else on this page is optional interplay
 that degrades gracefully when the other mod is absent.
 ## It plays nicely with other prison mods
 Contraband adds its own content rather than rewriting the base game's. It:
 - **Adds a new warden job** (search) rather than changing an existing one.
 - **Reuses vanilla warden behaviour** rather than overriding it, so anything that adjusts warden
  behaviour on the base class flows through to searches for free.
 - **Extends two escape-related behaviours at startup** so prisoners arm themselves and use what they
  are hiding when they break — inserted at a specific point, and it logs a warning if that anchor is
  missing rather than failing silently.
 - **Runs on a heartbeat** over held pawns for intake, improvisation, and tunnels — no hook on the
  capture event is needed because the heartbeat already visits every held pawn.
 The net effect: the surfaces other prison mods touch are mostly untouched here, so conflicts are the
 exception, not the rule.
 ## Foul Play — the carboy bridge
 **Foul Play** (the "Piss Nuke" mod) stays its own mod with its own front door, and yet its **carboy is
 a first-class contraband item.** This is the flagship demonstration of Contraband's *"items are
 content, subsystems are shared, mods are audiences"* principle, and it works two ways:
 1. **The carboy brings its own behaviour.** The carboy simply declares itself as contraband and points
   at the throw-the-carboy behaviour that lives in *Foul Play*. Contraband never has to know that
   behaviour exists — it just runs whatever the item brought with it.
 2. **A concealed carboy keeps its contents.** A carboy is not just "a jar" — it is a jar *of* a
   fermented blend, and that blend has to survive being concealed. When a carboy is intaken or
   smuggled, Contraband captures a label for its contents blindly; on redemption it hands the label
   back to Foul Play to restore the blend. **Contraband knows nothing about substances or
   fermentation** — that framework lives entirely in Foul Play. If Foul Play is absent, no content is
   captured and nothing breaks: a jar is just a jar. See
   [Concealment and Intake](Concealment-and-Intake.md).
 The dependency runs one way only: Foul Play bridges *to* Contraband (and to Core) if they are present;
 Contraband takes **no** dependency on Foul Play.
 ## Institution: Justice — the record is the shared bus
 Contraband and **Justice** never call each other. They meet on Core's criminal record — Contraband
 writes to it, Justice reads from it:
 | Contraband writes | Justice reads it into |
 |---|---|
 | times searched | Classification (security grade) |
 | times caught | Deterrence (colony-wide signal) |
 | escape attempts | Discipline / Parole (reform) |
 | contraband made | |
 - **Catching contraband feeds classification.** A prisoner repeatedly caught with shivs or foiled
  mid-tunnel racks up catches and escape attempts, which Justice's classification weighs into a higher
  security grade.
 - **And it feeds back.** Justice's deterrence signal flows *back* through Core's propensity, nudging
  every future intake / improvise / dig roll a Contraband pawn makes. A prison that catches and
  disciplines becomes a prison where fewer prisoners bother trying — without either mod referencing the
  other. Run Contraband alone and deterrence is a neutral 1.0; the record still routes the warden.
 ## Institution: Gangs — the contraband economy
 **Gangs** depends on Core, **Contraband**, and Justice, because a gang *is* a contraband economy:
 - Gang smuggling moves contraband through the same door intake and corruption use.
 - A gang's outside members are the natural caller for the **reach-in corruption** — paying a bent
  warden to make a delivery. That ability exists in Contraband but has no in-game trigger of its own;
  Gangs is what drives it. See [Corruption](Corruption.md).
 - Gang fights route to Justice's crime record, which then raises search priority here. The loop closes
  through Core again.
 ## Prison mods the suite is tested against
 | Mod | Interaction | Verdict |
 |---|---|---|
 | **Prison Commons** | it adjusts warden behaviour on the base class, and Contraband's search inherits that, so searches respect prison-commons/allowed areas **for free** | works by inheritance |
 | **Custom Prisoner Interactions** | it only touches the *named* vanilla warden jobs (chat, convert, enslave, release); it cannot see a brand-new job | no conflict |
 | **Prisoner Realism** | its escapes are for "mood prisoners" mid-break; a tunnel breakout hands off to the vanilla prison-break flow, which Prisoner Realism layers on. Tunnels **complement** it — they let ward patients and slaves who would never mood-break still, patiently, dig out | complementary |
 | **Prison Labor** | prisoners working outside the cell are still held pawns and still tracked; Contraband adds nothing to labor jobs. A work assignment is simply another place a disposed prisoner might come by materials | no conflict |
 | **Prisoner Recreation** | overlaps the *regime* feature — which now lives in **Institution: Justice**, not here, and is written to coexist with Prisoner Recreation | not Contraband's concern post-split |
 ## Load order
 1. Base game
 2. **Institution: Core** — required, loads before Contraband
 3. **Institution: Contraband** — this mod
 4. **Foul Play / Justice / Gangs** — any order after Core; each bridges if present
 ## The general rule
 If a mod adds prisoner behaviour by **changing vanilla warden jobs or the escape flow by name**, it
 will not see Contraband's additions, and Contraband will not see its — they pass each other harmlessly.
 If a mod adds a *new* warden job or escape behaviour of its own, it stacks. The one place to watch is
 another mod that *also* rewrites the same two escape-related behaviours wholesale; Contraband inserts
 its part at a specific point and logs a warning if that point is missing, so a load-order or conflict
 problem is visible in the log rather than silent.
 ---
 *Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
 Ward. Each stands alone; together they interlock.*
@@ -0,0 +1,201 @@
 # Concealment and Intake
 *How a hidden item exists without existing, how it gets onto a prisoner in the first place, and how
 it becomes real again.*
 This is the spine of the whole mod. Everything else — shivs, tunnels, searches, corruption — is a
 different way to add to, or remove from, the private stash this page describes.
 ## While it is concealed, there is no item
 The single most important rule:
 > The prison quietly tracks what each pawn is hiding. **Concealed contraband is not an item on the
 > map. It is a secret.** It is not in the gear tab, there is no icon, and the player is told nothing —
 > because an item you can see in the UI is not contraband, it is inventory, and there would be nothing
 > for a warden to discover and no reason to ever order a search.
 A concealed item is only a hidden fact about a pawn: what it is, how far along it is, what material it
 ended up made of, an optional source it is being whittled from, its tunnel state if it is a pick, and
 whatever it holds inside. It has **no physical object** anywhere in the world until one of two things
 happens:
 | Moment | What happens |
 |---|---|
 | The prisoner **uses** it | It materialises into their inventory as a real item |
 | A warden **finds** it | It is deleted; it never becomes an item at all |
 A corollary the search page leans on hard: **an empty search must still cost time.** If the search
 job only ever appeared when there was genuinely something to find, the mere *offer* of the job would
 be the discovery. You have to be able to toss a clean cell and come up with nothing.
 ## Where a thing can hide
 Every piece of contraband can hide in one of two places, and this decides **who can ever find it**:
 | Site | Holds | Found by |
 |---|---|---|
 | **On the body** | small: a shiv, pills, a phone | searching the **pawn** |
 | **In the cell** | bulky: a rifle, a carboy, a crude pick | tossing the **room** |
 A warden turning over a prisoner and their cell reaches both. The reason the two are split at all: a
 **constable** in Justice's policing layer, frisking a colonist named in a street crime, only reaches
 what is on the body, so whatever is under their floorboards stays there until somebody has grounds to
 search the *room*. The split between "who may search" and "what a search reaches" is deliberate — see
 [Warden Search](Warden-Search.md).
 ## Three kinds of contraband, and no list of items
 There is no hardcoded list of contraband item names. At the start of a game, the mod looks at every
 item in the game and decides, once, whether it counts as contraband, in one of three ways:
 1. **Explicit.** Anything a mod has deliberately marked as contraband. This is the opt-in, and it is
   how a mod plugs in its own behaviour for how the item is acquired, used, or used to escape.
 2. **Every drug** — recognised automatically.
 3. **Every weapon** that isn't destroyed when dropped — recognised from its **mass**.
 For anything not marked explicitly, the mod fills in how well it hides and where, so a modder never
 has to:
 | Kind | Test | Concealability | Hides |
 |---|---|---|---|
 | Hard drug | drug rated Hard | **0.75** | on body or in cell |
 | Other drug | any other drug | **0.5** | on body or in cell |
 | Light weapon | mass ≤ 2.0 kg | **0.7** | on body or in cell |
 | Heavy weapon | 2.0 kg < mass ≤ 10.0 kg | **0.35** | in cell only |
 | Very heavy weapon | mass > 10.0 kg | — | **not contraband** (a minigun hides nowhere) |
 **Concealability** runs 0 to 1, where **0 = a warden finds it every time and 1 = never**; higher is
 harder to find. Drugs and inferred weapons get **no crafting route** (you cannot synthesise yayo in a
 bare cell, and you cannot conjure a rifle) and **no special use behaviour** — because vanilla already
 knows what to do with them. A prisoner takes a drug on their own; an armed prisoner *is* the payload.
 Getting the item into the cell is the entire problem, and that is all these routes solve.
 Nothing here edits another mod's items. It is a one-time reading of each item's own stats. Modded
 drugs and weapons are covered without ever being named.
 ## The heartbeat
 The prison does its ongoing work on a heartbeat. Every **250 ticks** it visits every pawn who could
 be concealing something and does all the ongoing work: intake, tunnel progress, and improvisation. If
 nothing on the map can be self-made and no escape tools are in play, it does nothing and costs
 nothing.
 Because the heartbeat already visits every held pawn, intake needs no special trigger on the capture
 event: a pawn who is in custody but has not yet been processed is, by definition, one who was newly
 taken.
 ### Who counts as a concealer
 The set of pawns being tracked is **not** just prisoners. It is every pawn whose belongings are
 anyone's business — prisoners, slaves, ward patients, **and free colonists**:
 > A free colonist forbidden their drug by a drug policy or an ideoligion is precisely the pawn who
 > keeps a private stash — and vanilla already denies them, with no valve.
 Whether anyone may *search* a given concealer is a separate question with a separate answer (the
 warden's authority reaches prisoners; a future cop's reaches colonists). Tracking is pawn-agnostic;
 authority is not.
 ## Intake: the moment of capture
 Vanilla never strips a captive *on capture* — a downed pawn keeps whatever they walked in with, and
 the warden just hauls them to a cell. Intake is Contraband's answer to that gap, and it runs on the
 first heartbeat that sees a newly-held pawn:
 1. **Held only.** The pawn must be a person and in custody — prisoner, slave, or ward patient. A free
   colonist is tracked, but nobody frisks and processes *them* on the way into a cell, so their
   carried gear is never intaken.
 2. **Once.** Each captive is processed a single time; a later pass finds them already done and moves
   on. (It remembers by an ID, so it holds no ghost of a captive who has since died.)
 3. **Even while downed.** Intake runs *before* the "must be awake" gate. The stash a captive walked in
   with is hidden the moment they are in custody, not when they wake — everything *after* intake
   (whittling, digging) needs them awake, but hiding what is already on you does not.
 4. **Only what can ride on a body.** A thing can be intaken only if it is small enough to hide on the
   body. A shiv up a sleeve is intaken; a rifle or a suit of armour is too bulky to palm and stays as
   ordinary strippable gear the player confiscates for free.
 5. **Per-item disposition.** For each concealable thing the captive carries, the mod rolls whether
   *this* pawn would hide *this* item — a base chance of **0.6**, then scaled by the pawn's nature ×
   nurture (Core's propensity). The roll is **fixed per (pawn, item)** — a settled fact, not a fresh
   coin each tick. The frightened cook surrenders the knife; the disposed lifer palms it, and always
   would have.
 When a pawn does hide an item, the real object is **removed from the game** and a hidden secret takes
 its place, preserving what the item was made of and — critically — anything it holds inside.
 ## Preserving contents without understanding them
 A concealed vessel is not just "a jar" — it is a jar *of* something (hooch, piss, a fermented blend),
 and that something has to survive being hidden and come back when the item is used. Contraband stores
 what a vessel contains as a single opaque label and **has no idea what it means**.
 When the item is concealed, that label is captured; when the item comes back out, the label is used
 to pour the contents back into the freshly-made thing. This is the exact seam **Foul Play** uses to
 keep a smuggled carboy's contents intact. Without a bridge mod, no content is captured and nothing is
 lost — a shiv is just a shiv.
 Fermentation itself lives in Foul Play, not here. A concealed vessel comes back out **fresh** and
 ferments afterward like any other, which suits the theme: fresh-brewed piss is weak, and time is what
 makes it a weapon. (The prison remembers how long the vessel was hidden, for any bridge mod that
 wants to restore its aging, but it never acts on that number itself.) See
 [Compatibility](Compatibility.md).
 ## Redemption: the secret becomes real
 When a hidden item is finally used, it turns real:
 1. It is made from the material it was whittled from (or the item's default material, if it was never
   made from a material).
 2. Anything it held inside is poured back in.
 3. It is placed into the pawn's inventory. If that somehow fails, nothing is dropped and nothing is
   lost.
 4. The secret is cleared from the stash.
 The trigger for this is a breakout. When a prisoner enters an escape or assault-the-colony state, they
 will arm themselves and then use whatever they are hiding — the same moment a base-game prisoner would
 reach for a combat drug. The one contraband hook Ludeon wrote and then left reading an always-empty
 inventory is exactly where this slots in. For each thing a pawn is hiding:
 - **Inert contraband** (a drug, a stashed rifle — nothing special to "use"): just materialise it and
  get out of the way. Vanilla takes the drug on its own; a weapon in inventory is a weapon. But a
  stashed **weapon** only comes out for someone who would actually use it — the same person who would
  not stop to pick a rifle off the floor does not become a fighter because the knife was in their
  sock, and a pawn incapable of violence never does at all. If they qualify, the weapon moves into
  their hands; otherwise it stays hidden and they run. See [Improvised Weapons](Improvised-Weapons.md).
 - **Active contraband** (something with a special use — e.g. Foul Play's throw-the-carboy):
  materialise it, then hand off to that item's own use behaviour.
 ## Confiscation, and the door every route comes through
 When a warden finds contraband, it is simply removed. It **never becomes a real item** — the warden
 found it, and there is nothing to drop on the floor. (This is why searching is not a way for the
 colony to *acquire* a prisoner's drugs; it is a way to *deny* them.)
 At the other end, there is one single door that **every** supply route comes through — intake uses it,
 a bent warden uses it ([Corruption](Corruption.md)), and a smuggling gangmate
 ([Institution: Gangs](Compatibility.md)) uses it. It hands a prisoner something already finished and
 hidden, optionally with contents. One door, many keys.
 ## Saving
 Concealed contraband is saved with your game — the whole stash, the per-pawn search cooldowns, and who
 has already been intaken. On load, any secret whose pawn or item no longer exists is quietly dropped:
 prisoners who died or left take their secrets with them.
 ## Quick reference
 | Constant | Value | Meaning |
 |---|---|---|
 | Heartbeat | every 250 ticks | poll cadence for intake / tunnels / improvisation |
 | Intake base chance | 0.60 | per-item, before nature × nurture |
 | Intake gate | held + body-hideable | only pawns in custody, only items small enough to palm |
 | Hard-drug concealability | 0.75 | inferred from being a hard drug |
 | Other-drug concealability | 0.50 | inferred |
 | Light-weapon concealability | 0.70 | mass ≤ 2.0 kg, hides on body |
 | Heavy-weapon concealability | 0.35 | 2.0–10.0 kg, in cell only |
 | Unhideable mass | > 10.0 kg | not contraband |
 ---
 *Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
 Ward. Each stands alone; together they interlock.*
@@ -0,0 +1,111 @@
 # Corruption
 *A search is only as thorough as the warden running it, and a warden is a person with their own
 diligence and their own price.*
 The counter to contraband is the [warden search](Warden-Search.md) — but a search is not a machine. It
 is a human being with traits and a mood, and Contraband models that human being on **two axes, both
 read off the same vanilla traits, mood, and relationships — no new stat to maintain**:
 | Axis | Question | Effect on a search |
 |---|---|---|
 | **Diligence** | How hard do they look? | multiplies the find chance |
 | **Corruption** | How bent are they? | a flat chance to look away — and a route *into* the prison |
 This is *"what turns 'the game vs the player' into 'the player's own guards, each with an angle.'"* The
 prisoner you can control. The guard you assigned to watch them, you cannot.
 ## Diligence — how hard they look
 Diligence runs 0 to 1 and multiplies the whole find chance. A lax or miserable warden misses things a
 dutiful one would turn up. It starts from a baseline of **0.55** and moves with traits and mood:
 | Trait / factor | Δ Diligence | Reasoning |
 |---|---|---|
 | Industrious | +0.1 per degree | a hard worker searches hard |
 | Lazy | −0.1 per degree | a lazy one frisks gently |
 | Abrasive | +0.15 | happy to toss a cell |
 | Psychopath | +0.10 | thoroughness without squeamishness |
 | Kind | −0.20 | reluctant to be rough |
 | Mood | ×0.6 (miserable) .. ×1.1 (content) | morale is thoroughness |
 ## Corruption — their price
 Corruption also runs 0 to 1. In a search, a bent warden gets a flat chance to **look away** on each
 item they would otherwise have a shot at finding — that chance is their Corruption × 0.6, rolled per
 hidden item before the find roll. Corruption starts from a baseline of **0.04** (most guards are
 mostly honest) and moves with traits and mood:
 | Trait / factor | Δ Corruption | Reasoning |
 |---|---|---|
 | Greedy | +0.40 | the classic bent guard — everyone has a number |
 | Kind | +0.15 | looks the other way out of sympathy, not money |
 | Ascetic | −0.10 | wants nothing, so cannot be bought |
 | Abrasive | −0.05 | too surly to do anyone a favour |
 | Mood | ×1.6 (miserable) .. ×0.7 (content) | a happy guard is harder to tempt |
 ## The Kind warden is a double liability
 Read the two tables together and one trait jumps out. **Kind** *lowers* Diligence (−0.20) **and**
 *raises* Corruption (+0.15). The gentle guard both frisks softly and bends the rules out of pity — the
 worst warden you can put on a contraband detail, and the least obvious one, because "kind" reads as a
 virtue everywhere else in the game. Meanwhile **mood** cuts the same way on both axes: a miserable
 warden looks *less* hard and is *more* temptable. A depressed guard is a sieve at both ends.
 ## Worked examples
 Find chance for a hidden item is roughly the base find chance × Diligence, with a separate look-away
 chance (Corruption × 0.6) to ignore it entirely. Assume a mid-skill warden whose raw find chance on a
 shiv is around 0.30 before disposition:
 | Warden | Diligence | Corruption | Look-away/item | Net on a 0.30 shiv |
 |---|---|---|---|---|
 | Neutral, content | ~0.61 | ~0.03 | ~2% | thorough-ish: ~0.18 find |
 | Abrasive + Psychopath, content | ~0.88 | ~0.02 | ~1% | a nightmare for prisoners: ~0.26 find |
 | Greedy, content | ~0.61 | ~0.31 | ~18% | looks capable, pockets bribes |
 | Greedy, **miserable** | ~0.37 | ~0.62 | ~37% | ignores contraband over a third of the time |
 | Kind + **miserable** | ~0.25 | ~0.27 | ~16% | a sieve at both ends: ~0.07 find |
 (Numbers rounded; mood taken as content ≈ 100% or miserable ≈ 20%.) The takeaway is that **who you
 assign to search matters as much as whether you search at all.** A greedy, miserable warden is not a
 guard — he is a supply line you are paying to pretend otherwise.
 ## The bent warden as a supply route *in*
 Corruption is not only "looks away." The other half is reaching *in* — a bent guard who slips a
 prisoner contraband through the very same door a smuggler or a gangmate uses. Only what can ride on a
 body gets slipped across a handshake. Whether and when a guard does this is gated on that guard's
 Corruption.
 In Contraband on its own, this "smuggle in" ability exists but is not yet wired to an in-game trigger.
 It is the seam **Institution: Gangs** drives when a gang's outside members pay a bent warden to make a
 delivery, and the thing a planned secure-zone checkpoint that frisks *guards* is meant to catch.
 Search-side corruption (looking away) is fully live today; reach-in corruption is the hook the rest of
 the suite plugs into. See [Compatibility](Compatibility.md).
 ## How to play with it
 - **Vet your wardens.** A Greedy or Kind pawn on prison duty is a liability the trait tooltip won't
  warn you about. Ascetic and Industrious make the best searchers; Psychopath and Abrasive are
  brutally effective if you can stomach them.
 - **Watch mood.** A prison-duty warden in a slump is failing at both jobs — searching *and* not
  smuggling. Keep your guards content or rotate them out.
 - **Redundancy beats brilliance.** Because each search is one shot per prisoner per day and even a good
  warden misses a well-hidden shiv, a *second* diligent warden over time matters more than a single
  perfect search.
 ## Quick reference
 | Constant | Value | Meaning |
 |---|---|---|
 | Diligence baseline | 0.55 | before traits and mood |
 | Corruption baseline | 0.04 | most guards are mostly honest |
 | Diligence mood scale | ×0.6 .. ×1.1 | miserable → content |
 | Corruption mood scale | ×1.6 .. ×0.7 | miserable → content |
 | Look-away multiplier | ×0.6 | applied to Corruption, per item |
 | Smuggle payload | body-hideable contraband only | what fits in a handshake |
 ---
 *Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
 Ward. Each stands alone; together they interlock.*
@@ -1,102 +0,0 @@
 # Criminal Record — the history of fact
 If [Propensity](Propensity.md) is *suspicion* — "this pawn seems dangerous" — the criminal record is
 *fact*: "this pawn **has** escaped twice and shanked a guard." The two are deliberately different
 kinds of thing. Propensity is computed fresh from who a pawn is and how they're treated; a record is a
 durable log of what they've actually done, written once when it happens and read forever after.
 There is exactly **one criminal record per pawn**, and the whole suite shares it. Classification grades
 on it, parole gates on it, the deterrence loop reacts to it, and reintegration remembers it. Because
 everyone reads the same record, no two parts of the suite can disagree about a pawn's past.
 ---
 ## What a record remembers
 A record is a small set of counters plus two special marks. Core provides the record and keeps it
 safe; the individual events are logged by whichever mod they happen in.
 | What it tracks | Starts at | Meaning | Tracked by | Used by |
 |---|---:|---|---|---|
 | Crimes committed | 0 | count of committed crimes | Justice (and gang fights) | classification risk score, deterrence |
 | Escape attempts | 0 | breakout attempts | Contraband | classification risk score |
 | Contraband made | 0 | items brewed / whittled | Contraband | classification risk score |
 | Times searched | 0 | how often searched | Contraband (warden search) | search prioritisation |
 | Times caught | 0 | searches that found something | Contraband (warden search) | classification risk score |
 | Last crime | never | when the most recent crime happened | Justice | recency / cooldown checks |
 | Reform | 0 | rehabilitation score (see below) | Justice (discipline, parole) | **Propensity's Nurture**, parole gate, reintegration |
 | Pardoned | no | granted a clean slate after genuine reform | Justice (on release) | parole gate, reintegration |
 "Last crime" starts at *never* — a distinct value from "at the very first moment of the game."
 Everything else starts at zero / no.
 > **Who logs what.** Core is the *vault*, not the *clerk*. It hands out records and keeps them; the
 > actual "a crime just happened, add one" logging lives in the mod where the event occurs. The columns
 > above name which mod does that — Core itself only holds the fields.
 ## Reform — the pivot of the suite
 Most of a record is inert tallies. **Reform** is the one entry that feeds back into behaviour, and it's
 worth its own section. It's raised by good treatment and good conduct, decays without either, and can
 be driven negative by harsh punishment. A record is where a sentence's *outcome* is stored, and three
 systems lean on that one number:
 - **[Propensity](Propensity.md)'s Nurture** scales a pawn's disposition by their reform score — so a
  genuinely rehabilitated pawn (reform above 0) is calmer *for good*, and a prisonized one (reform
  below 0) is inflamed *for good*. This is how institutionalization and recidivism enter the game
  without a separate mechanic bolted on.
 - **Parole** (Justice) gates release on it: a pawn is only releasable once reform clears a threshold.
  It's the number that says "this one is ready."
 - **Reintegration** reads it to decide when a clean slate is earned — which is what the *pardoned*
  mark records.
 The negative range isn't a bug — it's the "hardened" end of the spectrum, and Nurture is written to
 expect it.
 ## Pardoned and blank records
 The **pardoned** mark flips on exactly once, after genuine reform, so reintegration can grant a clean
 slate without erasing the history that earned it — the counters stay, but the pawn is marked forgiven.
 A record counts as **blank** when nothing meaningful has ever been written to it: no crimes, no escape
 attempts, no contraband, never caught, reform still 0, not pardoned. Note what blankness *ignores*:
 times searched and the last-crime time aren't part of the test. A pawn who was searched and found clean
 — searched but never caught, never a crime — still counts as blank. That's intentional: being
 *checked* is not a mark against you, only being *found* is.
 ---
 ## Records are created only when needed
 Records are made lazily. A pawn only gets a record the first time something is actually **written** to
 it — a crime, a search that found something, a reform change. Simply **reading** a pawn's disposition
 never creates one.
 That distinction matters because Propensity's Nurture reads a pawn's reform score constantly, on every
 pawn on the map, as part of judging their mood. If merely checking disposition created a record, every
 mood check would stamp a criminal file onto every innocent pawn on the map. Because reading only peeks
 — and tolerates a pawn having no record at all — the innocent stay off the books.
 The rule the whole suite follows: **something happened → a record is created and written; just looking
 → no record is created.**
 ---
 ## Persistence
 Records save with your game and reload with it, and there's exactly one shared store for the whole
 colony — no mod keeps its own private copy, which is what keeps them all agreeing with each other.
 On load, that store cleans itself up. Three kinds of record get dropped:
 1. **Records of pawns who are gone** — dead or removed. They take their records with them.
 2. **Corrupt entries** — a guard against a broken save.
 3. **Blank records** — anything still blank. There's no reason to keep a file that records nothing.
 The upshot: **records are cheap and self-cleaning.** Anything that never got a real mark written to it
 simply evaporates on the next load, so the save never bloats with one empty file per pawn ever glanced
 at.
 ---
 *Part of the **Institution** suite.*
@@ -1,88 +1,126 @@
-# Institution: Core — Wiki
+# Institution: Contraband
-*The shared foundation of the **Institution** suite: a set of RimWorld 1.6 mods about what an
+*Prisoners get hold of things they should not have. Wardens turn the cell over looking for them.*
 institution does to the people inside it, and the crime, policing, and justice that put them there.*
-Core is the engine every other Institution mod runs on. **On its own it changes nothing you can
+This is the player-facing wiki for **Institution: Contraband**, a RimWorld 1.6 mod. It documents
-see** — no items, no jobs, no new menus. It sits completely quiet until another Institution mod is
+every mechanic with the real numbers, explains why each one works the way it does, and tells you how
-installed on top of it. You install Core only because something else asks for it.
+to play with them — and against them.
-This wiki explains what that hidden engine actually does once a mod above it puts it to work — down to
+> **Note on scope.** Contraband was recently *split*. It is now one thing: the **physical smuggling
-the exact numbers, because knowing how the numbers move is half the fun of running a prison.
+> loop** of a prison. The engine it used to carry — a pawn's criminal propensity, the criminal
-
+> record, and which pawns count as "in custody" — now lives in **Institution: Core**, which this mod
---
+> requires. The response systems (classification, deterrence, discipline, parole, regime) went to
 > **Institution: Justice**, and the gang network to **Institution: Gangs**. When this page mentions
 > "the record" or "a pawn's propensity," those belong to Core; Contraband reads them.
 ## The one idea
 The whole Institution suite rests on a single sentence:
 > **Every pawn has a criminal propensity on a spectrum — nature (traits) × nurture (circumstance,
 > mood, treatment) — and the colony can police it.**
-That single sentence is the whole suite. Colonists, prisoners, and slaves drift toward crime on a
+Contraband is the half of that sentence you can *hold in your hand*. A propensity is abstract until a
-continuous spectrum; a policing and justice layer discovers, catches, punishes, reforms, or paroles
+disposed prisoner files a blade off his bunk, palms a twist of yayo on the way into a cell, or starts
-them. Core is where the *spectrum* itself lives — before anyone is caught, before there is a record to
+digging. Contraband is where the spectrum becomes an object with edges.
 read, before there is a warden to search them.
-## Why a shared engine
+## Vanilla built the demand and forgot the supply chain
-The propensity idea didn't start out abstract. It grew up twice, in two different mods: one deciding
+RimWorld already ships a fully-built junkie. Raiders spawn addicted and carrying combat drugs. You
-which drunk, miserable pawn starts a mess, and one deciding which prisoner whittles a shiv the moment a
+down one, capture strips everything, and now withdrawal grips them in the cell. A prisoner already
-door opens. Both were asking the same real question — *would **this** pawn do it?* — and each answered
+*seeks* a drug on their own, and already *ignores* the forbidden flag inside their own cell.
 it its own way, which meant they could disagree about who was dangerous.
-Core exists so they stop disagreeing. When the contraband system, the justice system, and the gang
+Put a drug within reach of an addicted prisoner and the base game makes them take it. Today. The
-system all read one disposition engine, they agree about who is dangerous instead of each judging it
+consumer, the craving, the reach, the ignore-forbidden — all of it already works.
 separately and drifting apart. The pawn who is "the scary one" is the scary one to every part of the
 suite at once. That coherence — not any single number — is the point of a shared foundation.
-Core carries exactly the three things every Institution mod needs and none should own alone, and
+What does **not** exist is any answer to two questions:
 nothing else:
-| Pillar | Answers | Page |
+| Vanilla has | Vanilla lacks |
 |---|---|
 | A prisoner who wants contraband | Any route for contraband to reach the cell |
 | A warden with fifteen jobs | A sixteenth called *search* |
 The base game's warden can chat, convert, feed, execute, enslave, release, suppress — and cannot look
 in a pocket. Contraband builds exactly the missing two halves: **supply** and **search**. It does not
 need to build the junkie, because Ludeon already did.
 ## Concealment is a secret, not an item
 This is the load-bearing design decision:
 > **While it is concealed, there is no item.**
 A hidden shiv is not in the gear tab. There is no icon. There is no stack on a shelf. The player is
 told **nothing**. The item does not become a real object in the world until exactly two moments:
 - when the prisoner **uses** it (it appears in their inventory), and
 - when a warden **finds** it in a search (it is confiscated and never becomes an item at all).
 Why go to the trouble? Because *an item you can see in the UI is not contraband* — it's inventory, and
 there would be nothing to discover and no reason to ever order a search. The whole tension of the
 system is that **you never know**. A warden you send to toss a cell might find a blade, might foil a
 tunnel, or might waste twenty minutes on a prisoner who was hiding nothing — and that empty search
 still has to cost, or the mere *offer* of the job would be the discovery.
 Read the full lifecycle in **[Concealment and Intake](Concealment-and-Intake.md)**.
 ## The four supply routes and the one counter
 | Route | What it is | Page |
 |---|---|---|
-| **Propensity** | *Would this pawn do it?* (nature × nurture) | [Propensity](Propensity.md) |
+| **Intake** | A captive hides the small contraband they walked in with | [Concealment and Intake](Concealment-and-Intake.md) |
-| **Criminal record** | *What has this pawn actually done?* (one history per pawn) | [Criminal Record](Criminal-Record.md) |
+| **Improvise** | Whittle a shiv from the cell's own furniture | [Improvised Weapons](Improvised-Weapons.md) |
-| **Secured context** | *What kind of hold is this pawn under, and who may search them?* | [Secured Context](Secured-Context.md) |
+| **Tunnel** | Dig out under the perimeter with a filed pick | [Tunnels](Tunnels.md) |
 | **A bent warden** | A greedy or over-kind guard smuggles *for* a prisoner | [Corruption](Corruption.md) |
 | **The counter** | A prioritized cell toss that reads the tells | [Warden Search](Warden-Search.md) |
-The distinction between the first two is the spine of the whole design: **propensity is suspicion, a
+And because every guard is a person with their own diligence and their own price, the search is only
-record is fact.** Propensity says "this pawn *seems* dangerous"; a record says "this pawn *has*
+as good as who you send — see **[Corruption](Corruption.md)**.
 escaped twice and shanked a guard." Keeping them separate is what lets the colony act on evidence
 instead of on vibes.
-## The pages of this wiki
+## How everything is contraband without a list
- **[Propensity](Propensity.md)** — nature × nurture in full: the trait-weight table, the nurture
+Contraband names no items. It recognises three kinds of thing:
-  multiplier ladder, the disposition formula with worked examples, and why each pawn's roll is fixed
+
-  rather than re-rolled.
+1. **Anything explicitly marked as contraband** — the opt-in, with pluggable behaviour a mod can
- **[Criminal Record](Criminal-Record.md)** — everything a record remembers, who fills in each part,
+   supply.
-  how it persists across saves, and why *reform* is the pivot of the whole suite.
+2. **Every drug** — vanilla's, Vanilla Expanded's, mods that don't exist yet. Hard drugs conceal
- **[Secured Context](Secured-Context.md)** — the Free / Prisoner / Slave kinds, what counts as
+   better (0.75 vs 0.5).
-  "held" versus what counts as "able to hide something," and why the suite keys off this instead of
+3. **Every weapon** — how well it hides, and where, is decided by its **mass**. A knife rides on the
-  "is a prisoner."
+   body; a heavy gun goes under the floor; a minigun (over 10 kg) hides nowhere.
- **[Treatment Engine](Treatment-Engine.md)** — the shared rehabilitation maths: mark a condition
+
-  treatable, reduce it a little each session by skill and facility quality, and build a recovery track
+It reads the item's own stats rather than editing anything. Nothing changes another mod's items.
-  toward discharge. Ward's psychiatric care and Justice's reform run on this one engine.
+Details in [Concealment and Intake](Concealment-and-Intake.md) and [Compatibility](Compatibility.md).
- **[Modder API](Modder-API.md)** — the "for modders" page: the tools any mod can call to build on
+
-  Core. Players can skip it.
+## Index
 - **[Concealment and Intake](Concealment-and-Intake.md)** — the secret model, where a thing can hide,
  the three kinds of contraband, intake on capture, redemption, and how a smuggled vessel keeps its
  contents.
 - **[Improvised Weapons](Improvised-Weapons.md)** — the shiv whittled from furniture, how its
  material carries through, the damage tell, and who reaches for it in a breakout.
 - **[Tunnels](Tunnels.md)** — the Prison-Architect dig under the perimeter, which pawns dig, and how a
  search uncovers the shaft.
 - **[Warden Search](Warden-Search.md)** — the prioritized search, how tells and the record drive
  priority, what a search does, and how it feeds back.
 - **[Corruption](Corruption.md)** — Diligence and Corruption from traits and mood, how they scale a
  find, and the bent warden who looks away or smuggles in.
 - **[Compatibility](Compatibility.md)** — the Core dependency, the Foul Play bridge, Justice/Gangs
  interplay, and the prison mods the suite is tested against.
 ## The suite
-Each mod stands alone as an install; together they form one system. Core sits underneath everything
+Each mod stands alone as an install; together they form one system.
 else.
-| Mod | What it adds | Needs |
+| Mod | Owns | Depends on |
 |---|---|---|
-| **Institution: Core** (this) | the propensity / record / context engine | base game only |
+| **Institution: Core** | propensity, criminal record, secured context | base game |
-| **Institution: Contraband** | concealment, improvised shivs, tunnels, warden search, warden corruption | Core |
+| **Institution: Contraband** (this) | concealment, intake, shivs, tunnels, search, corruption | Core |
-| **Institution: Justice** | classification, deterrence, discipline, parole, regime, and **policing** (colony crime → weighed arrest) | Core, Harmony |
+| **Institution: Justice** | classification, deterrence, discipline, parole, regime | Core |
-| **Institution: Gangs** | gangs as contraband economies: joining, smuggling, rivalry, fights-as-crime | Core, Contraband, Justice |
+| **Institution: Gangs** | gangs as contraband economies | Core, Contraband, Justice |
-| **Institution: Ward** | psychiatric care — a prisoner treated, not punished, on Core's treatment engine | Core, Harmony |
+| **Foul Play** | vessel + substance + throw framework; the Piss Nuke; bridges its carboy in as contraband | standalone |
-| **Foul Play** | the vessel + substance + throw framework, home of the "Piss Nuke" | standalone; bridges to Core + Contraband |
+| **Ward** | a ward prison mode | — |
 ## Requirements & load order
 - **RimWorld 1.6.** Core needs only the base game — no Harmony, no DLC, no other mod.
 - Load Core **before** any other Institution mod in your mod list.
 ---
-*Part of the **Institution** suite.*
+*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
 Ward. Each stands alone; together they interlock.*
@@ -0,0 +1,176 @@
 # Improvised Weapons
 *The supply route you cannot deny — because you are obliged to furnish the cell, and the furniture is
 the raw material.*
 You have to give a prisoner a bed. RimWorld will nag you until you do. That bed is a frame of wood, or
 steel, or — if you built a nice prison — plasteel. Give a disposed prisoner a season of unsupervised
 time with it and they will file a blade off it. **The prison's own furnishings are the arsenal, and
 better furniture is worse.**
 ## The shiv
 The shiv is a crude stabbing weapon: *"A blade filed off a bed frame and wrapped in cloth for a grip.
 Barely a weapon — but a barely-a-weapon in a cell you thought was empty is a dead guard."*
 | Stat | Value |
 |---|---|
 | Tech level | Neolithic |
 | Mass | 0.4 kg |
 | Concealability | **0.75** (hides very well — it rides on the body) |
 | Hides | on body or in cell |
 | Point (Stab) | power 7, cooldown 1.5 s |
 | Handle (Blunt) | power 5, cooldown 1.6 s |
 | Use | none — an armed prisoner *is* the payload |
 Its stats come from its material: it can be made of metal, wood, or stone. A wood shiv is feeble; a
 plasteel one is vicious. That is the whole point of the harvest mechanic — you never furnished a cell
 thinking of it as an armoury, but that is what it is.
 ## Who whittles: the disposition gate
 Not just "any prisoner." Three things must all be true:
 1. **Held.** The pawn is a prisoner, slave, or ward patient. Free colonists do not whittle shivs in
   the commons — *yet* (the concealment layer already tracks them; only the authority to act on them
   is missing).
 2. **Disposed.** A base chance of **0.10**, scaled by Core's nature × nurture. It is a *fixed fact*
   about the pawn — the mistreated, high-propensity lifer chews his bed apart; the frightened cook
   never does, and never would have, no matter how many times you reload.
 3. **Material in reach.** There is a workable source (see below).
 The base is deliberately low. Most prisoners are not making weapons. When one is, that is a fact about
 *who they are and how you keep them*, and the tell it leaves is meant to point you at exactly that
 pawn.
 ## The source: what counts as raw material
 The prisoner looks for the nearest reachable, damageable, usefully-made piece of furniture:
 - **Their own assigned bed first** — it is right there in the cell.
 - Otherwise the **closest artificial building within 12 tiles** that qualifies.
 To be a workable source, a piece of furniture must be:
 | Requirement | Why |
 |---|---|
 | Made of a material | you cannot whittle a blade out of nothing |
 | Damageable | it has to take a beating |
 | Made of metal, wood, or stone | cloth and leather cannot be filed into a blade |
 | Reachable, even through danger | they have to get to it |
 This is also the counter-play. A cell furnished only in cloth and hydroponics offers nothing to file.
 A steel bed offers a steel shiv. **What you build the cell out of decides whether it can become a
 weapon, and how nasty that weapon is.**
 ## Harvest by damage: the tell *is* the mechanic
 Each heartbeat, a whittling prisoner chips at the source — roughly **1.2% of its max hit points per
 worked poll**, as blunt damage.
 The damage is not a side effect — it is the point. A gnawed bed is **probable cause**. The same tick
 that advances the shiv damages the furniture, and that visible wear is what
 [Warden Search](Warden-Search.md) reads to send a guard to the *right* prisoner first: a badly damaged
 bed shoots a prisoner to the top of the search priority list. Whittling a shiv is loud, in the only
 sense that matters — it leaves a mark you can act on.
 Because the source takes real damage, a determined prisoner can **reduce a piece of furniture to
 wreckage and move on to the next**: if the source is destroyed before the shiv is finished, they look
 for another, and if there is none, the route **stalls** (progress is kept, not lost). A materially
 poor cell is a real defence — the prisoner cannot make progress with nothing to file.
 ## How long, and the material it becomes
 A shiv takes roughly **1.5 unsupervised days** of active work, jittered ±25% each poll so no two
 shivs finish on the same schedule.
 When it is finished, it happens **silently** — the player is told nothing. Two things happen:
 - **Material carry-through.** The shiv is made of whatever the source was made of. A wood bed yields a
  wood shiv, a plasteel bunk a plasteel one, and its combat stats follow.
 - **The record.** The pawn's tally of contraband made ticks up (in Core's record). That number feeds
  the warden's future suspicion of this pawn and, if you run **Institution: Justice**, their security
  classification.
 ## The shiv comes out in a break — and who reaches for it
 A hidden shiv is inert until a breakout. When a prisoner enters an escape or assault-the-colony state,
 they will use what they are hiding — but a **weapon** only comes out for someone who would actually
 use it. That is the same test that decides whether an escapee even bothers to pick a weapon off the
 floor.
 This matters because **vanilla escapees never arm themselves at all.** The base game has the behaviour
 for opportunistically grabbing a weapon, and simply leaves it out of the escape flow, so a base-game
 prisoner walks out unarmed, always. Arming is genuinely new behaviour, so it is kept rare enough that
 when it happens you recognise *who* did it.
 ### Would this pawn arm itself?
 First a **hard gate**: a pawn who is incapable of violence never arms, ever — a pacifist who picks up
 a rifle is not a rare event, it is a bug. Otherwise the chance is the pawn's **disposition** (who they
 are, fixed) times their **circumstance** (what is happening right now), capped at **0.85** and settled
 once per pawn as a fixed fact.
 **Disposition** — who they are, fixed, nothing about today changes it. A base of 0.10, scaled by trait
 and skill:
 | Factor | Value |
 |---|---|
 | Bloodlust | ×2.5 (highest applicable trait only — not a stack) |
 | Psychopath | ×2.0 |
 | Brawler | ×1.8 |
 | Wimp | ×0.3 |
 | Kind | ×0.4 |
 | skill | scales with their best of Shooting or Melee → range **0.5 .. 2.0** |
 *Being captured in a raid does not make someone a fighter* — plenty of prisoners are cooks and
 conscripts. A weapon is only worth grabbing if you know what to do with it, hence the skill term.
 **Circumstance** — what is happening right now, live:
 | Condition | Effect | Reasoning |
 |---|---|---|
 | Health < 50% | ×0.4 | badly hurt people run or crawl; they don't seek a fight |
 | ≥ 2 other prisoners escaping within 12 tiles | ×2.0 | a crowd emboldens; one man slips out, six men riot |
 | An armed colonist within 20 tiles | ×1.8 | now a weapon is not bravado, it's the plan |
 ### Which weapon they reach for
 An arming escapee prefers, in order:
 1. **Their own dropped weapon** — the gun they carried when you downed them, still lying where it fell
   within 45 tiles. The base game remembers where it fell and then never uses that for prisoners. *"A
   man walking back to the spot where his own rifle fell is a better story than a man rummaging through
   your stockpile."* A prisoner does not care that you marked it forbidden.
 2. **Anything to hand** within 18 tiles — but only for a pawn over a higher disposition floor (0.35).
   Rummaging a stockpile is a further step than grabbing your own gun back.
 A concealed shiv slots into this the natural way: a prisoner who has been sitting on a blade and who is
 the sort to use it does not leave it in his pocket — it goes straight into his hand. The pawn who
 would *not* arm keeps it hidden and runs — and the shiv survives to be found in a later search, or
 used in a later break.
 ## Not only shivs: the crude pick
 The same whittling behaviour makes the **crude pick** — filed off furniture exactly the same way, with
 the same disposition gate and the same damage tell — but its purpose is a tunnel rather than a fight.
 See [Tunnels](Tunnels.md).
 ## Quick reference
 | Constant | Value | Meaning |
 |---|---|---|
 | Improvise base chance | 0.10 | before nature × nurture; fixed per pawn |
 | Damage per worked poll | ~1.2% of source max HP | blunt; the visible tell |
 | Source search radius | 12 tiles | own bed first, then nearest workable furniture |
 | Time to finish a shiv | ~1.5 active days | jittered ±25% per poll |
 | Workable material | metal / wood / stone | cloth and leather cannot be whittled |
 | Shiv concealability | 0.75 | hard to find on the body |
 | Arm chance cap | 0.85 | after disposition × circumstance |
 | Own-weapon reach | 45 tiles | their dropped weapon |
 | Any-weapon reach | 18 tiles | scavenge floor 0.35 disposition |
 ---
 *Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
 Ward. Each stands alone; together they interlock.*
@@ -1,238 +0,0 @@
 # Modder API — building on Core
 Core is a library. It has no XML, no defs, no UI — its entire purpose is to be *called*, by the other
 Institution mods and by yours. This page is the public surface, with the one seam that matters most
 (`Propensity.DeterrenceFactor`) explained in full.
 > **This page is for modders.** Every other page in this wiki is written for players; this one is the
 > technical surface for building on Core. If you just want to know how the mod plays, start at the
 > [Home](Home.md) page and the [Propensity](Propensity.md) / [Criminal Record](Criminal-Record.md) /
 > [Secured Context](Secured-Context.md) / [Treatment Engine](Treatment-Engine.md) pages instead.
 Everything here is verified against the three source files in `Source/Core/`.
 ---
 ## The namespace is `Contraband`
 Before anything else: **all of Core's types live in `namespace Contraband`**, not `Core` and not
 `Institution`. This is historical — the engine was extracted from Institution: Contraband — and it is
 not going to change under you, but it does mean your `using` looks slightly surprising:
 ```csharp
 using Contraband;   // Propensity, CriminalRecord, GameComponent_CriminalRecords,
                    // SecuredKind, SecuredContext, SecuredContexts,
                    // TreatmentProgram, TreatableConditionExtension
 ```
 Reference the assembly `InstitutionCore.dll` (packageId `flan.institution.core`) and load your mod
 after Core.
 ## The public surface at a glance
 | Call | Returns | Creates state? | Use for |
 |---|---|---|---|
 | `Propensity.Nature(pawn)` | `float 0..1` | no | fixed trait-based disposition |
 | `Propensity.Nurture(pawn)` | `float` (multiplier) | no | live circumstance multiplier |
 | `Propensity.Would(pawn, baseChance, salt, cap=0.85)` | `bool` | no | the seeded yes/no for a behaviour |
 | `Propensity.DeterrenceFactor` | `Func<Pawn,float>` field | — | the seam a justice layer fills |
 | `GameComponent_CriminalRecords.For(pawn)` | `CriminalRecord` | **yes** (blank on first ask) | write paths |
 | `GameComponent_CriminalRecords.PeekFor(pawn)` | `CriminalRecord?` | no | read paths |
 | `SecuredContexts.Of(pawn)` | `SecuredContext?` | no | one pawn's hold kind |
 | `SecuredContexts.OnMap(map)` | `IEnumerable<SecuredContext>` | no | every held/free pawn on a map |
 | `TreatmentProgram.HasTreatableCondition(pawn)` | `bool` | no | is there a marked condition to work through? |
 | `TreatmentProgram.ReduceConditions(pawn, strength)` | `void` | mutates hediffs | run one session's worth of treatment |
 | `TreatmentProgram.FacilityQuality(pawn)` | `float 0.5..1.5` | no | scale a session by the room's quality |
 | `TreatmentProgram.AdvanceRecovery(pawn, def, amount)` | `float` | **yes** (recovery hediff) | build a discharge / parole track |
 All of these are `static` and null-safe. None throws on a null pawn; they return `0.05`/`1f`/`null`/
 `false` as appropriate. See the [Propensity](Propensity.md), [Criminal Record](Criminal-Record.md),
 and [Secured Context](Secured-Context.md) pages for the mechanics behind each.
 ---
 ## Asking "would this pawn?"
 The idiomatic pattern for a new behaviour is: pick a **base rate**, pick a **stable salt** unique to
 your question, and call `Would`. Do not re-implement the nature/nurture math — that is the whole point
 of the shared engine.
 ```csharp
 using Contraband;
 // A unique, STABLE salt for this specific question. Any constant int works; keep it
 // distinct from other questions so the rolls stay independent per behaviour.
 private const int Salt_WouldStealMeds = 0x5EED01;
 if (Propensity.Would(pawn, baseChance: 0.08f, salt: Salt_WouldStealMeds))
 {
    // this pawn, under these conditions, is the kind who does this
 }
 ```
 Because the roll is seeded on `pawn.thingIDNumber ^ salt`, the answer is a stable fact per pawn per
 question and survives save/reload — so you can ask it repeatedly and get a consistent character, and
 different salts give you independent facts about the same pawn. Pass a custom `cap` if `0.85` is the
 wrong ceiling for your behaviour (e.g. a lower cap for something that should always keep a large
 chance of not happening).
 If you only need the ingredients — say, to display a disposition readout or gate a threshold — read
 `Nature` and `Nurture` directly. Institution: Gangs, for instance, joins a pawn to a gang when
 `Nature(pawn) * Nurture(pawn)` clears its own threshold, computed from these two calls rather than
 from `Would`.
 ## Reading and writing records
 Follow the one rule from the [Criminal Record](Criminal-Record.md) page — **write with `For`, read
 with `PeekFor`** — so read paths never litter the save with blank records.
 ```csharp
 using Contraband;
 // WRITE: an event happened, so we need a record to write to.
 CriminalRecord rec = GameComponent_CriminalRecords.For(pawn);
 rec.contrabandMade++;
 // READ: peek, and tolerate null (the pawn may have no record yet).
 CriminalRecord existing = GameComponent_CriminalRecords.PeekFor(pawn);
 if (existing != null && existing.reform < 0f)
 {
    // this pawn has been hardened
 }
 ```
 Core owns the storage and persistence; you own the meaning of your own events. Do not keep your own
 per-pawn crime dictionary — that is exactly the fragmentation Core exists to prevent.
 ## Working across hold kinds
 Reduce a pawn to its context and branch on the *predicate*, not the label:
 ```csharp
 using Contraband;
 SecuredContext? maybe = SecuredContexts.Of(pawn);
 if (maybe is SecuredContext ctx && ctx.IsHeld)
 {
    // prisoner OR slave OR ward patient -- all covered, no special cases
 }
 // Sweep everyone the suite cares about on a map:
 foreach (SecuredContext c in SecuredContexts.OnMap(map))
 {
    if (c.CanConceal) { /* consider hoarders too, not just the held */ }
 }
 ```
 `Of` returns `null` for anything the suite does not model (animals, mechs, the dead), so a `null`
 check is your "not our business" branch.
 ## Running a treatment programme
 Core carries the maths of "sustained attention in a secured facility reduces a marked condition and
 builds a recovery track toward discharge" — the shared engine behind Ward's psychiatric care and
 Justice's rehabilitation. Mark a hediff treatable with `TreatableConditionExtension`, then drive it
 from your own job or interaction:
 ```csharp
 using Contraband;
 float strength = skill * TreatmentProgram.FacilityQuality(pawn) * share;   // your own blend
 TreatmentProgram.ReduceConditions(pawn, strength);                          // lower the condition
 if (!TreatmentProgram.HasTreatableCondition(pawn))
 {
    TreatmentProgram.AdvanceRecovery(pawn, MyDefOf.Recovery, 0.15f * strength);   // build discharge
 }
 ```
 You own the interaction mode, the job, the recovery hediff (give it a negative `severityPerDay` so it
 decays without attention), and the discharge alert; Core owns only the numbers. Full formulas and the
 consumer contract are on the **[Treatment Engine](Treatment-Engine.md)** page.
 ---
 ## The `DeterrenceFactor` seam
 This is the most important extension point in Core, and the reason Core can remain a **dependency-free
 leaf** while a colony-wide deterrence feedback loop runs *through* it.
 ### What it is
 ```csharp
 // In Propensity:
 public static System.Func<Pawn, float> DeterrenceFactor = _ => 1f;
 ```
 A single static delegate. `Nurture` multiplies its result by `DeterrenceFactor(pawn)` as its last
 step. Out of the box the delegate returns `1f` for every pawn — perfectly neutral — so **Core alone
 behaves as if deterrence did not exist.**
 ### What it is *for*
 Deterrence is a property of the whole colony's climate of order: a well-policed colony should deter
 everyone a little; a lawless one should embolden them. That is a feedback loop — catching and
 punishing *one* pawn changes the disposition of *the rest*. But deterrence itself is a justice-layer
 concept, and Core must not know the justice layer exists.
 The seam resolves the tension. Core defines *where* the colony's climate multiplies into disposition
 (the last line of `Nurture`) without defining *what* that climate is. From the source:
 > *"Deterrence lives in the Justice layer, so Core reads it through the seam above — neutral until
 > Justice fills it. This one seam is what keeps Core a dependency-free leaf despite the deterrence
 > feedback loop running through it."*
 ### How Institution: Justice fills it
 When Institution: Justice loads, it assigns the delegate, pointing it at its own live deterrence
 level. The shape it installs maps a `0..1` deterrence reading to a multiplier that straddles `1.0`:
 ```csharp
 // Illustrative — this lives in Institution: Justice, not Core.
 Propensity.DeterrenceFactor = pawn =>
 {
    float level = DeterrenceLevelFor(pawn.Map);      // 0 = lawless, 1 = tightly policed
    return Mathf.Lerp(1.3f, 0.7f, level);            // lawless emboldens, order deters; neutral at 0.5
 };
 ```
 | Deterrence level | Factor | Effect on disposition |
 |---|---:|---|
 | `0.0` (lawless) | `1.3` | everyone ~30% more inclined |
 | `0.5` (baseline) | `1.0` | neutral — a default colony sits exactly here |
 | `1.0` (tightly policed) | `0.7` | everyone ~30% less inclined |
 *(The `1.3 → 0.7` range, neutral at the `0.5` baseline, are Justice's numbers, documented here for context;
 Core only guarantees the neutral `1f` default. Confirm against Institution: Justice's own source for
 its current values.)*
 ### How to fill it yourself
 If you are writing your own policing or morale layer and want it to feed disposition the same way,
 just assign the delegate — ideally at game load, and ideally composing with whatever is already there
 rather than clobbering it:
 ```csharp
 using Contraband;
 using UnityEngine;
 // Compose: fold your factor into any existing one (e.g. Justice's) instead of overwriting.
 var previous = Propensity.DeterrenceFactor;
 Propensity.DeterrenceFactor = pawn => previous(pawn) * MyClimateFactorFor(pawn);
 ```
 Two cautions. First, it is a single static field — if two mods both *assign* it (rather than compose),
 the last one wins, so compose when you can. Second, keep your factor bounded and centred near `1.0`:
 `Nurture` has no clamp on this term, so an extreme factor multiplies straight through into every
 pawn's `Would` roll. Return `1f` when you have nothing to say, exactly as the default does.
 ### Why a delegate and not a dependency
 The alternative — Core calling into Justice — would make Core depend on Justice, inverting the whole
 topology and breaking Core's promise that it references *only the base game*. A single assignable
 `Func<Pawn,float>`, neutral by default, lets the feedback loop run through Core while the arrow of
 dependency still points only *at* Core. It is the smallest possible seam that buys the largest possible
 decoupling, and it is why Core can sit at the bottom of the suite with zero dependencies of its own.
 ---
 *Part of the **Institution** suite.*
@@ -1,212 +0,0 @@
 # Propensity — nature × nurture
 Propensity is the suite's disposition engine. It answers one question and only one: *"would **this**
 pawn do it?"* — never *"would a prisoner,"* never *"would a colonist."* Every behaviour in the suite
 that hinges on a pawn's character comes back to this, so crime, contraband brewing, escape arming, and
 gang recruitment all read the same answer instead of each guessing.
 The model is deliberately old-fashioned: **nature × nurture.**
 - **Nature** is a fixed property of the person — their traits. Almost nobody is strongly disposed, and
  this never changes over a pawn's life.
 - **Nurture** is what the colony has done *to* them — mood, mistreatment, unmet needs, the shadow a
  sentence leaves. This is the half **you** control, and the half no other mod models.
 Good conditions pull nurture down; neglect and cruelty push it up. A saint left to rot can cross the
 line; a monster kept content and deterred may never act. Both of those stories are possible by design.
 ---
 ## Nature — who they are
 Every pawn starts from a **baseline of 0.05** — the floor of the human condition in this model:
 everyone is capable of *something*, most people barely. From there, each trait the pawn has adds or
 subtracts, and the total is held to the 0–1 range (never below 0, never above 1).
 ### Trait weights
 Traits are matched **by name**, so if a trait's mod isn't installed that entry is simply skipped.
 That's how Core uses Vanilla Traits Expanded's dark traits when VTE is present without *requiring* VTE
 to be installed.
 | Trait | Weight | Source | Note |
 |---|---:|---|---|
 | Psychopath | **+0.45** | Vanilla | no empathy; the heaviest single input |
 | Kleptomaniac | **+0.40** | Vanilla Traits Expanded | counted if VTE is installed |
 | Bloodlust | **+0.35** | Vanilla | enjoys violence |
 | Pyromaniac | **+0.30** | Vanilla Traits Expanded | counted if VTE is installed |
 | Greedy | **+0.25** | Vanilla | wants more than their share |
 | Abrasive | **+0.15** | Vanilla | friction with everyone |
 | Ascetic | **−0.15** | Vanilla | wants little, takes little |
 | Kind | **−0.30** | Vanilla | the strongest pull *down* |
 Core adds no traits of its own — it reads the ones the game and your other mods already provide.
 Vanilla's own dark traits count right alongside VTE's.
 ### Worked Nature values
 Because weights simply add and then clamp, Nature is easy to read by hand:
 | Pawn | Arithmetic | Nature |
 |---|---|---:|
 | Ordinary pawn (none of the above) | 0.05 | **0.05** |
 | Kind pawn | 0.05 − 0.30 = −0.25 → clamp | **0.00** |
 | A single Greedy trait | 0.05 + 0.25 | **0.30** |
 | Psychopath | 0.05 + 0.45 | **0.50** |
 | Psychopath **and** Kind | 0.05 + 0.45 − 0.30 | **0.20** |
 | Greedy + Abrasive | 0.05 + 0.25 + 0.15 | **0.45** |
 | Psychopath + Bloodlust + Kleptomaniac | 0.05 + 0.45 + 0.35 + 0.40 = 1.25 → clamp | **1.00** |
 Two things fall out of this. First, the clamp isn't decorative: a Kind pawn floors at exactly `0`
 (nature can never make them *disposed*, only never disposed), and a stacked monster ceilings at `1`.
 Second, traits genuinely net against each other — a Kind Psychopath is a real, middling `0.20`, not a
 contradiction.
 Most rolled pawns sit at or near the `0.05` floor. That's intended: a colony full of ordinary people
 is supposed to be mostly safe on nature alone. What makes them dangerous is nurture.
 ---
 ## Nurture — what you have done to them
 Nurture is a **multiplier**. An ordinary pawn under ordinary conditions sits at **1.0**. The number
 rises as things go wrong and falls as they go right. Each lever below stacks on top of the last.
 ### The multiplier ladder
 | Lever | Factor | Applies when | Stacks? |
 |---|---|---|---|
 | **Despair** | ×2.5 | mood below 20% | mutually exclusive with "badly kept" |
 | **Badly kept** | ×1.6 | mood 20–35% | mutually exclusive with "despair" |
 | **Held & unhappy** | ×1.4 | held **and** mood below 40% | on top of the mood lever |
 | **Prisonization** | × (depends on reform, see below) | the pawn has a non-zero reform score | on top |
 | **Deterrence** | × (the colony's climate of order) | always (neutral 1.0 with only Core) | on top |
 The two mood levers are either/or: a pawn is either in despair *or* badly kept, never both. "Held &
 unhappy" is separate and multiplies again — so a mistreated prisoner in despair compounds
 `2.5 × 1.4 = 3.5` before anything else. That is a badly run cell.
 ### Prisonization — the reform lever
 The reform lever is where a sentence leaves a permanent mark. A pawn's **reform score** runs from
 about −1 to +1 and turns into a multiplier:
 | Reform score | Meaning | Factor |
 |---:|---|---:|
 | **+1.0** | fully rehabilitated | 0.50 |
 | +0.5 | improving | 0.75 |
 | 0 | untouched (no effect) | *1.00* |
 | −0.5 | hardening | 1.25 |
 | **−1.0** | prisonized | 1.50 |
 | beyond +1.2 | (over-reformed) | floors at **0.40** |
 | beyond −2.0 | (utterly broken) | ceilings at **2.00** |
 Reform is nominally a 0-to-1 rehabilitation score, but harsh punishment can drive it **negative** —
 that's the "hardened, prisonized" end. Within the realistic −1…+1 range the factor spans 0.5…1.5; the
 0.4 / 2.0 limits only bite at the extremes, catching a pawn who's been endlessly punished or endlessly
 rehabilitated.
 Propensity only *reads* this score — nothing in Core moves it. The Justice layer's discipline and
 parole are what nudge it up or down, which is how institutionalization and recidivism enter the game
 without a separate mechanic. A pawn broken by a brutal prison stays broken (nurture ×1.5) after
 release; a pawn genuinely reformed stays calmer (×0.5) for good. The scar rides on one number.
 ### Deterrence — the climate of order
 The final lever multiplies by the colony's overall **climate of order**. **With only Core installed
 it's neutral — a flat 1.0** — because Core by itself doesn't know what deterrence is. Install
 **Institution: Justice** and it fills this in: a well-policed colony pulls the factor below 1 and
 deters everyone a little; a lawless one pushes it above 1 and emboldens them. That's what makes
 catching and punishing *one* pawn matter to the disposition of *the rest*.
 With only Core installed, this lever does nothing, and that is correct. The technical details of how a
 mod fills in deterrence are on the [Modder API](Modder-API.md) page.
 ---
 ## Would — the full roll
 Nature and Nurture are ingredients. The full roll is the meal: the actual yes/no for a specific
 behaviour at a specific base rate. For a given behaviour, the chance works out to:
 > **chance = base rate × (0.1 + Nature × 2) × Nurture**, capped at 85%.
 Three things are happening there:
 1. **Base rate** is the behaviour's own dial — how likely an *average* pawn is to do this particular
   thing (a rare act uses a small number, a common one a larger). Core doesn't decide it; whichever
   system is asking does.
 2. **(0.1 + Nature × 2)** is the nature amplifier. It spans **×0.1** (a saint, Nature 0) to **×2.1**
   (Nature 1). At the common `0.05` floor it's **×0.2** — so an ordinary pawn is one-fifth as likely
   as the base rate, while a maxed monster is over twice as likely — *before* nurture.
 3. **× Nurture** applies circumstance on top, and the whole thing is capped at **85%** by default.
   Nobody is ever a dead certainty; there's always slack. A behaviour that wants a harder or softer
   ceiling can set its own cap.
 ### Worked example 1 — an ordinary colonist, content
 Base rate 10%, an ordinary pawn (Nature 0.05), good mood so Nurture 1.0:
 - nature term = 0.1 + 0.05 × 2 = 0.2
 - chance = 0.10 × 0.2 × 1.0 = 0.02 → **2%**
 Two percent — and, critically, **fixed**. For this pawn and this question it's a settled 2% coin that
 either comes up or doesn't; it isn't re-flipped every moment.
 ### Worked example 2 — a mistreated psychopath prisoner
 A Psychopath + Bloodlust prisoner (Nature 0.85), mood 15% (despair ×2.5), held and unhappy (×1.4),
 reform −0.5 (hardening → ×1.25), Core-only so deterrence 1.0. Base rate 10%:
 - nature term = 0.1 + 0.85 × 2 = 1.8
 - nurture = 2.5 × 1.4 × 1.25 = 4.375
 - chance = 0.10 × 1.8 × 4.375 = 0.7875 → **~79%**
 Same base rate as example 1, same engine — but nature and a badly-run cell have turned a 2% pawn into
 a near-certainty. The player did that, lever by lever.
 ### Worked example 3 — hitting the cap
 A fully stacked monster (Nature clamps to 1.0), in despair (×2.5) and held & unhappy (×1.4), in a
 lawless colony where Justice has set deterrence to 1.4. Base rate 10%:
 - nature term = 0.1 + 1.0 × 2 = 2.1
 - nurture = 2.5 × 1.4 × 1.4 = 4.9
 - raw chance = 0.10 × 2.1 × 4.9 = 1.029
 - capped at **85%**
 The raw product blew past 100%; the cap reins it to 85%. Even here, a 15% sliver of "not today"
 survives. That sliver is deliberate — it keeps the worst pawn a character with a bad day coming, not a
 scripted event.
 ---
 ## The fixed roll — characters, not a dice cup
 Each pawn's answer to "would they?" is **fixed** by two things: who the pawn is (their permanent
 identity) and which behaviour is being asked about. It is not re-rolled from scratch each time. This is
 the single most important design decision on this page, and it's worth being precise about why.
 **Save/reload stability.** Because the answer is tied to the pawn's permanent identity and the specific
 question — not to the live random stream — asking "would they?" gives the same answer before and after
 a save/reload, as long as the inputs (traits, mood, reform) are the same. You can't scum a reload to
 re-roll a pawn into a different person. *Who* they are doesn't shift under them on a reload.
 **A character, not a moment-to-moment lottery.** If the game flipped a fresh coin every tick, any pawn
 would eventually do anything if you waited long enough. Fixing the roll instead makes "would this pawn
 pocket a shiv?" a settled fact about that pawn under those conditions — what makes them a character,
 not a dice cup.
 **Live circumstance still bites.** The roll freezes the *identity*, not the *situation*. Nurture is
 recomputed live, so as mood collapses or reform hardens, the same pawn's chance climbs and the same
 fixed coin can flip from "no" to "yes." The pawn who wouldn't have acted last month acts now — not
 because the dice changed, but because you let their world get worse.
 **Different questions, independent answers.** Each behaviour is its own separate question, so the
 answers don't leak into each other: a pawn who would pocket a shiv is not therefore a pawn who would
 inform on a cellmate. One pawn can be reliably one kind of trouble and reliably not another, and that
 pattern is stable across the whole game.
 ---
 *Part of the **Institution** suite.*
@@ -1,88 +0,0 @@
 # Secured Context — the kind of hold a pawn is under
 The suite has a rule that looks small and is load-bearing: **nothing keys off "is this a prisoner."**
 It keys off the *kind of hold* a pawn is under. That one step of indirection is why a ward patient, a
 slave, and (later) anyone inside a secure zone get the same concealment, search, schedule, and needs
 machinery for free, without any feature hard-coding a single pawn status.
 A pawn's secured context boils down to one of three kinds and the question "who, if anyone, may search
 them." Everything downstream reads that, so a new feature works across every kind of hold the day it's
 written, and a new *kind of hold* works across every existing feature the day it's added.
 ---
 ## The three kinds
 | Kind | Who it is | May search them | Can conceal? | Held against their will? |
 |---|---|---|---|---|
 | **Free** | a free colonist | *no one* — until a secure-area or policing layer grants standing | **yes** — they can hoard | no |
 | **Prisoner** | a prisoner of the colony | the **warden** | yes | **yes** |
 | **Slave** | a slave (Ideology DLC) | the **overseer** | yes | **yes** |
 Two subtleties fall out of this table:
 - **Free colonists can still conceal.** A free colonist can hoard contraband, but no one has standing
  to search them until a secure-area or policing layer grants it. Freedom isn't innocence — it's only
  the absence of an authority allowed to check.
 - **Prisoner and Slave differ only in who holds the keys.** Both are "held"; the search authority is
  the warden for one and the overseer for the other. Features that only care "is someone entitled to
  search this pawn" read whether the pawn is *held* and never branch on which.
 ## Two questions, two axes
 The context answers two different questions, and picking the right one is the whole skill of using it:
 | Question | True for | Ask it when you care about… |
 |---|---|---|
 | **Is this pawn held?** | Prisoner, Slave | **custody** — who is under the colony's control, who can be disciplined, whose cell can be searched |
 | **Could this pawn be hiding something?** | Free, Prisoner, Slave (any real pawn) | **contraband** — who could be *hiding* something, regardless of status |
 For example, [Propensity](Propensity.md)'s Nurture uses *held* in its "held & unhappy compounds" lever
 — it only wants to pile the ×1.4 penalty on a pawn the colony actually holds and mistreats, not on a
 grumpy free colonist. A warden-search feature, by contrast, cares who *could* be hiding something to
 decide who's even worth checking, and then checks standing to decide whether it's *allowed* to.
 ---
 ## How a pawn gets classified
 Any pawn resolves to one context, or to **nothing at all** if the suite doesn't model them:
 - Animals, mechs, and the dead are simply not the suite's business — they resolve to nothing, and
  every sweep and check skips them without a special case.
 - A pawn is tested as **prisoner** first, then **slave**, then **free colonist**. So a pawn who is
  somehow both a colonist and imprisoned is classified by their *hold* first.
 Keeping "nothing at all" separate from "a free pawn we track" is deliberate: there's a real difference
 between "a free pawn we watch" and "a pawn we don't model at all," and collapsing them would let
 non-colony pawns leak into colony machinery. A single sweep can walk every prisoner, slave, and
 colonist on a map in one pass, skipping everything that resolves to nothing.
 ---
 ## Why not just "prisoner"?
 This is the design decision the whole page exists to justify. If every feature checked "is this pawn a
 prisoner" directly, then:
 - adding **slaves** to a feature would mean revisiting every feature;
 - adding a **ward patient** mode would mean revisiting every feature;
 - adding a future **secure-zone** concept would mean revisiting every feature.
 By routing all of them through one question — *what kind of hold is this?* — a new kind of hold is
 added *once*, and every existing feature inherits it. The concealment, search, and needs machinery
 never has to learn what a slave is; it only ever asked whether the pawn is *held* and whether they
 *could conceal*.
 ### The deliberately-absent Ward kind
 There's no separate "ward patient" kind, and its absence is intentional. A committed ward patient
 **is** a prisoner in the game's own sense — Institution: Ward builds its committed-patient mode on top
 of vanilla's prisoner system — so such a pawn already counts as **Prisoner** here, with no special case
 and no dependency from Core (or Contraband) onto Ward. Every feature treats a ward patient exactly as
 it treats any prisoner. The right amount of new work to support Ward's hold semantics was zero, and
 that's the payoff of keying off the kind of hold instead of the label.
 ---
 *Part of the **Institution** suite.*
@@ -1,94 +0,0 @@
 # The Treatment Engine — shared rehabilitation
 *The shared maths behind every "fix a held pawn over time" system in the suite.*
 Core carries one more thing every rehabilitation-style system needs and none should own alone: the
 maths of a **treatment programme**. Sustained attention in a secured facility reduces a marked
 condition, the room's quality helps or hurts, and once there's nothing left to reduce a **recovery
 track** builds toward a state where the pawn can be discharged.
 It exists for the same reason the propensity engine does. Two systems want the identical loop pointed
 at different things — **Ward** treats the mental illness that got a pawn committed; **Justice**
 rehabilitates the disposition that got one imprisoned — and without a shared engine each would grow its
 own copy and drift apart. Core owns **only the maths**. Which interaction enrols a pawn, which
 conditions and moods carry the flavour, which jobs run the sessions, and which alert fires on discharge
 all live in the mod using it.
 > The engine does something only when there's a real condition to work through, and does nothing
 > otherwise. A colony that never marks anything treatable never notices it exists.
 ---
 ## How treatment plays out
 A condition has to be **marked treatable** before a programme can touch it (Ward marks mental illness
 this way; a modder or player can mark anything — see the [Modder API](Modder-API.md) page). Once a
 condition is marked, treatment runs in sessions:
 1. **Each completed session removes a slice of the condition's severity.** The base amount is **0.12
   severity per session**, *before* it's scaled by the treating pawn's skill, the facility's quality,
   and how much of the session that patient actually gets. When a condition's severity reaches zero
   it's gone.
 2. **A full course is several sessions by design.** The programme has to be *sustained* — you can't
   fix a pawn in a single visit.
 3. **Once nothing is left to treat, continued care builds a recovery track** from 0 toward 1
   (discharge-ready). Fix the illness first, then stabilise.
 4. **The recovery track decays on its own if you stop.** Recovery you stop maintaining slips back down
   — which is what makes the whole thing a loop you keep up, not a one-time unlock.
 ---
 ## The numbers
 ### Facility quality
 The room the treatment happens in scales every session between **0.5×** (grim) and **1.5×**
 (excellent):
 | Room | Factor |
 |---|---:|
 | Bare (0 impressiveness) | 0.60 |
 | Decent (~48 impressiveness) | 1.00 |
 | Impressive (108+ impressiveness) | 1.50 (capped) |
 | Outdoors / no room | 0.75 |
 The limits are deliberate: a grim, filthy, cramped facility heals worse and a calm clean one better,
 but a palace can't trivialise the work the programme costs (1.5× ceiling), and even treating a pawn out
 in the open is a poor makeshift room (0.75×), not a hard zero.
 ### Reducing a condition
 Each marked condition drops by **0.12 × the session's combined strength** per session, and vanishes
 when it hits zero. That combined strength is the treating pawn's skill × the facility quality above ×
 the patient's share of the session — so all three inputs matter, and a good therapist in a good room
 working one-on-one is worth many times a poor one splitting attention in a bad room.
 ### Building recovery
 The recovery track is a plain 0-to-1 progress bar toward discharge. Continued care adds to it (capped
 at 1.0) and — crucially — it carries a slow decay, so it slips back down without sustained attention.
 The mod using the engine decides what reaching the top actually *unlocks* (Ward: a "ready for
 discharge" alert).
 ---
 ## Who uses it
 - **[Institution: Ward](https://git.onetick.ninja/flan/rimworld-ward)** — psychiatric care. Marks
  mental-illness conditions treatable (Rim Disorders' depression, anxiety, PTSD, and OCD, when that mod
  is present), runs warden counselling sessions, and builds a recovery track toward a "ready for
  discharge" alert. The reference example.
 - **Institution: Justice** — rehabilitation. Its *reform* score is the disposition axis punishment
  moves; the recovery track is the natural home for a *sustained rehabilitation programme* that gates
  parole on the same shared engine, so the two systems agree on "getting better" instead of each
  inventing it.
 "Reduce the condition, *then* build recovery" is the shape Ward uses, but it isn't forced: a
 rehabilitation system with no clinical condition to clear (like Justice's reform) can build a recovery
 track from the very first session and read its level to gate a parole.
 The point, exactly as with propensity: one engine, two uses, no drift.
 ---
 *Part of the **Institution** suite.*
@@ -0,0 +1,158 @@
 # Tunnels
 *The Prison-Architect dig: a disposed pawn goes down, not through — under the ground and everything
 built on it, out past the last wall you were relying on.*
 A locked door stops a prisoner who wants to walk out. It does nothing at all about a prisoner who
 digs. This is the escape that ignores your perimeter, because it does not cross it — it goes beneath
 it. It is slow, it is quiet, and it works for pawns who would never join a mood-driven riot.
 ## The crude pick
 The dig needs a tool. The crude pick is filed off the cell's own furniture exactly the way a shiv is —
 same disposition gate, same damage-to-furniture tell; see
 [Improvised Weapons](Improvised-Weapons.md). Where the shiv is a weapon, this is a *way out*: it
 carries no combat stats and is never equipped.
 | Stat | Value |
 |---|---|
 | Description | *"Useless as a weapon and useless above ground — but pointed downward, patiently, it is a way out that no lock and no guard can see."* |
 | Max HP | 60 |
 | Mass | 1.2 kg |
 | Concealability | **0.5** |
 | Hides | in cell only (too bulky to ride on a body) |
 | Deteriorates | yes |
 Because it can only hide in the cell, a warden turning over the *room* can find the pick itself — and,
 far more easily, the hole it is digging.
 ## A second secret riding on the first
 A tunnel is *"the third thing a contraband item can be, after 'made' and 'used in a break': a thing
 you dig your way OUT with, quietly, over days."* It is deliberately **not a job** you can catch a pawn
 performing. There is no supervised task a warden could walk in on and interrupt — only a secret that
 grows and a wall that eventually gives. The dig advances on the same 250-tick heartbeat that makes
 contraband, so *the same search that finds a shiv can find the tunnel*.
 The pick must first be **made** (or smuggled). Only once it is finished does the dig begin, as a
 second, longer secret carried on the same hidden pick.
 ## Who digs
 Digging gates on three things:
 1. **A person, and held** — prisoner, slave, or ward patient.
 2. **The disposition to dig for weeks:** a base chance of **0.08** — deliberately below the shiv's
   0.10. *"Fewer pawns will dig for weeks than will palm a shiv."* It is a fixed fact about the pawn.
 3. **A viable plan exists** — there has to be somewhere to surface (see below).
 This is the entire reason tunnels live in Contraband and not in a prisoner-only escape mod:
 > It works for prisoners **and ward patients** alike. Prisoner Realism's escapes are for "mood
 > prisoners" mid-break bashing a door, and a committed ward patient is never that pawn. A patient with
 > a filed-down pick and the disposition to use it can still, slowly, dig out — and nothing else in the
 > ecosystem lets them.
 ## Planning the dig: aim for the wilderness
 The target is **not** the cell wall. *"You do not go through the wall, you go under it."* The pawn
 aims for the **nearest wilderness** — the first standable spot, scanning outward up to **60 tiles**,
 that opens onto the map edge and is not the room they are held in.
 Two consequences fall straight out of that:
 - **Depth is your defence, and a single wall is not.** A tunnel from a deep bunker is a long dig; a
  tunnel from a shack against the map edge is a short one. Wrapping one more wall around a cell does
  almost nothing — the dig already ignores intervening walls entirely.
 - **A fully enclosed, map-locked base with no reachable edge has nowhere to surface.** The plan fails,
  no progress is made, and the tunnel **stalls** — progress is kept, not lost. Seal the map and the
  shaft simply waits.
 ### How long
 Dig time scales with how deep the cell sits — about **6 cells of depth per day**, clamped between 3
 and 15 days, and jittered ±25% each poll:
 | | Days |
 |---|---|
 | Minimum (shallow cell near the edge) | **3** |
 | Maximum (deep bunker) | **15** |
 | Per day of digging | ~6 cells of depth |
 The floor of 3 days keeps even the shortest tunnel a *real threat window* you have time to catch; the
 ceiling of 15 keeps the deepest from being effectively forever.
 ## The tell: spoil
 A dig has to go somewhere, and the dirt is where you notice it. Each dig tick, about half the time,
 the pawn drops one tile of dirt filth where they are digging:
 > A dirt floor swallows it; a paved cell shows it — exactly where a player might notice.
 It is cheap and occasional on purpose: enough that a paved cell slowly accumulates a suspicious mess,
 not so much that it spams filth or litters a clean cell every tick. If you floor your cells, spoil is a
 genuine visual cue that someone is digging.
 ## Finding a tunnel in a search
 A tunnel is *"a second, far less hideable secret."* The pick hides at concealability 0.5, but the
 **shaft** gives itself away in proportion to how far along it is. When a warden search reaches the
 cell, an extra find chance is added on top of the tool's normal find chance — scaling up to **+0.40**
 at a nearly-finished tunnel.
 So a routine cell toss that finds a shiv can also catch a dig in progress — *"the same guard patrol
 that finds a shiv finds the hole"* — and the deeper the shaft, the harder it is to miss. A foiled dig
 counts against the prisoner the same as one that ran: on discovery, their escape-attempt tally ticks
 up, which raises this pawn's future search priority sharply (a known tunneller is the prisoner a warden
 checks first — see [Warden Search](Warden-Search.md)). The full find math is on the
 [Warden Search](Warden-Search.md) page.
 ## Breakout
 When the dig finishes:
 1. **Re-plan the exit** so it is correct even if the base changed during the weeks of digging.
 2. **Breach the outer wall or fence** the tunnel comes up beside — the *outermost* impassable wall or
   fence between the cell and the surfacing point. It is destroyed, leaving a visible hole the colony
   must repair, and proof of how they got out. An open perimeter needs no breach.
 3. **Record the attempt** — it happened whether or not they get clear of the map.
 4. **Surface beyond the perimeter.** They dug all the way out, so they emerge *outside*, not in the
   yard, with a little spoil dirt to mark where they came up.
 5. **Hand off to vanilla.** Now that they are loose and outside, the base game's prison-break flow —
   and anything layered on it, e.g. **Prisoner Realism** — takes it from there. A pawn already outside
   who no longer qualifies as an in-prison escapee simply flees on their own; the breach and the
   emergence are the real outcome regardless.
 The player gets one message: *"{pawn} has tunnelled out under the perimeter and escaped."* The tunnel
 and the pick are spent together.
 ## How to defend against it
 | Defence | Effect |
 |---|---|
 | **Floor the cells** | spoil dirt becomes visible; you can *see* a dig |
 | **Search known offenders** | a logged escape attempt is the heaviest single term in search priority |
 | **Deny the pick's raw material** | no workable furniture, no pick — same starve as the shiv |
 | **Depth** | a deeper cell is a longer dig and a wider window to catch it |
 | **Seal the map** | no reachable edge means the tunnel stalls indefinitely |
 Note what does **not** help much: adding perimeter walls. The dig goes under them and only breaches the
 *last* one on the way out.
 ## Quick reference
 | Constant | Value | Meaning |
 |---|---|---|
 | Dig base chance | 0.08 | before nature × nurture; fixed per pawn |
 | Wilderness search radius | 60 tiles | how far out it looks for a surfacing point |
 | Cells per day | 6 | dig speed vs. cell depth |
 | Min / max dig time | 3 / 15 days | clamps on depth ÷ 6 |
 | Spoil chance per dig tick | 50% | one tile of dirt filth |
 | Extra find chance | up to +0.40 | scales with how far along the dig is |
 | Pick concealability | 0.5 | in cell only |
 | On discovery / breakout | escape attempt logged | counted either way |
 ---
 *Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
 Ward. Each stands alone; together they interlock.*
@@ -0,0 +1,181 @@
 # Warden Search
 *The sixteenth warden job vanilla never wrote. A guard turns the cell over, and might find nothing —
 which is exactly why it has to cost.*
 The warden can chat, convert, feed, execute, enslave, release, suppress, and eleven other things.
 Searching a prisoner is not one of them, and no such job exists anywhere in the base game. Contraband
 adds it as a **new** warden job, not a change to an existing one, and builds it around a single hard
 rule: **the search must be able to come up empty.**
 ## Authority vs. act
 The design splits one job into two halves:
 | Half | Question it answers | Notes |
 |---|---|---|
 | The search **assignment** | **Who** may be searched? | it is ordinary warden work — a warden already has the run of the prison, so no new authority is invented |
 | The search **act** | **What** is a search? | walk to the pawn, turn them over, resolve |
 > The assignment is the authority. The act is just the act.
 Why bother splitting them? Because the enforcement layer is meant to grow. A future **Institution:
 Police** module adds a *second* authority — a cop who may stop and frisk a **free colonist** — reusing
 the same act with a **narrower reach** (a street frisk gets what is on the body, not what is under the
 floorboards). That module is an *addition*, not a rewrite, precisely because "who may search" and
 "what a search reaches" were never welded together.
 ## Who gets searched
 The search is warden work, and it sits at a deliberate spot in the warden's priorities:
 | Property | Value | Why |
 |---|---|---|
 | Work type | Warden | it is warden work |
 | Priority within warden work | **below feeding** | a starving prisoner matters more than a hidden shiv |
 | Capacities needed | Manipulation, Sight | you search with your hands and eyes |
 | Ranked by suspicion | **yes** | pick the right prisoner, not the nearest |
 That last one — ranking by suspicion rather than distance — is what lets a gnawed bed and a thick
 record send the warden to the *right* prisoner first.
 A search is offered only if all of these hold: the warden should be looking after this prisoner, the
 per-prisoner cooldown is up, the prisoner is **awake, not downed, and not in a mental state**, and the
 warden can reach them.
 Note what is **not** checked:
 > Whether the prisoner is actually hiding anything. **The warden does not know. Nobody knows until the
 > cell is turned over.** If the job were only offered when there was something to find, the mere
 > appearance of the job would BE the discovery, and searching would stop being a gamble the player
 > pays for in warden-hours. An empty search has to be possible, and has to cost.
 ### The cooldown
 The same prisoner cannot be turned over more than **once per day** (60,000 ticks). You cannot
 brute-force a well-hidden shiv by re-searching the same prisoner ten times in an hour. Every search is
 one shot, and then that prisoner is off the list for a day.
 ## Priority: the search reads the tells
 Everyone is worth a routine toss; the tells push a prisoner up the queue. Priority is built up like
 this:
 - **Base 4** — a routine toss for every prisoner.
 - **Up to +12 for a gnawed bed** — scaled by how damaged their owned bed is. A badly damaged bed
  shoots to the top.
 - **Up to +8 for their record** — prior catches (×2 each), contraband made in the past (×0.5 each),
  and foiled escape attempts (×3 each, **the heaviest term**), capped at +8 so the record cannot
  completely swamp fresh probable cause.
 | Term | Weight | Meaning |
 |---|---|---|
 | Base | 4 | a routine toss for every prisoner |
 | Gnawed bed | up to +12 | how far below full HP their owned bed sits |
 | Times caught | ×2 | already caught with contraband before |
 | Contraband made | ×0.5 | has finished contraband in the past |
 | Escape attempts | ×3 | **the heaviest term** — a known tunneller is checked first, every time |
 | (record cap) | +8 max | the record cannot completely swamp fresh probable cause |
 The record is only read here, never created. The base of 4 for everyone is not an accident —
 **innocent prisoners still get frisked**, because the search must be able to come up empty or its mere
 offer would be the discovery.
 **Worked example.** A prisoner whose bed sits at 40% HP (so 60% missing), with 2 prior catches and 1
 foiled tunnel:
 > 4 + (12 × 0.6) + min(8, 2×2 + 1×3) = 4 + 7.2 + 7 = **18.2**
 versus **4** for a clean prisoner with an intact bed. The warden walks past the quiet one and goes
 straight for the one who has been busy. This closes the loop
 [Improvised Weapons](Improvised-Weapons.md) opens: whittling a shiv chews the bed, the damage is
 probable cause, and the warden's *suspicion* — not the player's eye — sends them to search.
 ## The act: what a search does
 The searcher walks to the subject, spends a **900-tick** turn with a progress bar, then resolves.
 Resolution always does two things, hit or miss:
 1. Starts the daily cooldown on that prisoner.
 2. Ticks up how many times this pawn has been searched — *"classification and the guard's future
   suspicion read how often this pawn has been turned over."*
 Then it goes through everything the subject is hiding that this search can **reach** (a full warden
 search reaches both the body and the cell; a narrower future street-frisk reaches only the body). If
 nothing is reachable, the job ends here — the time was still spent, and the player is told nothing.
 ### Find math, per hidden item
 For each reachable secret, the chance to find it is built like this:
 - Start from a **base of 0.35**, plus **0.03 for each level of the warden's Social skill**.
 - Scale by how concealable the item is: the factor pivots at concealability 0.5. A drug at 0.5 is
  average (×1.0), a shiv at 0.75 is halved (×0.5), a heavy weapon at 0.35 is boosted (×1.3).
 - If the item is a **tunnel in progress**, add its extra find chance (up to +0.40 for a nearly
  finished shaft), and the ceiling rises.
 - Multiply the whole thing by the warden's **Diligence** — a lax, kind, or miserable guard scales it
  down.
 - Before the find roll, a **bent** warden gets a flat chance to look the other way (their Corruption ×
  0.6) even on an item they would otherwise have found.
 - The chance is clamped to between 0.02 and 0.95 (0.98 for a tunnel).
 Reading it in plain terms:
 - **Skill raises the ceiling; concealability lowers it.** Each level of the warden's Social skill adds
  a little; a well-hidden item takes a lot of it back.
 - **A good warden still misses a well-hidden shiv more often than not.** A level-8 Social warden
  searching for a 0.75-concealability shiv is already well under a coin-flip *before* Diligence scales
  it down further.
 - **A tunnel is a different story.** The pick hides at 0.5, but a nearly-finished shaft adds up to
  +0.40 and the cap rises to 0.98 — the deeper the dig, the harder it is to miss. A routine cell toss
  catches a dig in progress.
 - **The warden's own thoroughness and price** enter last: Diligence multiplies the whole chance down
  for a lax, kind, or miserable guard, and Corruption gives a bent guard a flat chance to look the
  other way even on an item they would otherwise have found. Both are on the
  [Corruption](Corruption.md) page.
 ### On a find
 - The item is confiscated — it **never becomes a real object**, nothing drops on the floor.
 - The prisoner's times-caught tally ticks up (raising future suspicion, feeding classification).
 - If it was a tunnel, their escape-attempt tally ticks up too — a foiled dig counts the same as one
  that ran.
 The player gets a message — *"{warden} searched {prisoner} and found hidden {item}"*, or the tunnel
 variant. If nothing is found the player is told **nothing**: they do not learn there *was* something,
 only that the warden's time was spent.
 ## Writing back to the record
 Every outcome updates Core's criminal record, which is what makes the search a *loop* rather than a
 one-off dice roll:
 | Tally | Updated when | Read by |
 |---|---|---|
 | Times searched | every search, hit or miss | priority, suspicion, classification |
 | Times caught | a find | priority (×2), classification |
 | Escape attempts | a foiled tunnel | priority (×3, heaviest), classification |
 If you run **Institution: Justice**, those same tallies drive a prisoner's security classification and
 feed the deterrence signal — a prison that catches contraband becomes a prison that classifies its
 troublemakers correctly and deters the next attempt. If you run Contraband alone, the tallies still
 route the warden. See [Compatibility](Compatibility.md).
 ## Quick reference
 | Constant | Value | Meaning |
 |---|---|---|
 | Base find chance | 0.35 | before skill and concealability |
 | Per Social level | +0.03 | skill raises the ceiling |
 | Find chance clamp | 0.02 .. 0.95 | (0.98 for a tunnel) |
 | Search duration | 900 ticks | one turn, hit or miss |
 | Search cooldown | 60,000 ticks (1 day) | per prisoner |
 | Priority base | 4 | every prisoner is worth a routine toss |
 | Gnawed-bed weight | up to +12 | how far below full HP their bed sits |
 | Record weight | up to +8 | caught ×2 + made ×0.5 + escapes ×3 |
 | Default reach | body + cell | narrowed by a future street-frisk |
 ---
 *Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
 Ward. Each stands alone; together they interlock.*