Player-facing wiki rewrite + scenario FAQ

FAQ.md

@@ -0,0 +1,145 @@
+# FAQ — handling what Institution throws at you
+
+New situations the suite introduces, and what to actually do about them. Grouped by where the trouble
+comes from. Every layer is a checkbox in **Options → Mod Settings** — if a whole category of problem
+isn't for you, turn that layer off and it stops immediately.
+
+---
+
+## Escapes & contraband
+
+**A prisoner is digging a tunnel under my wall!**
+Order a warden to **search** them — a search can turn up the digging tool and end the tunnel, and a
+half-dug shaft is easier to spot than the pick that started it. Tunnels take days, so you have time.
+Prevention: house dangerous prisoners in **interior** cells with no short line to the wilderness, and
+keep them searched. See [Tunnels](contraband/Tunnels.md) and [Warden Search](contraband/Warden-Search.md).
+
+**My prisoner keeps having a shiv / weapon on them.**
+Contraband is hidden — you won't see it in the gear tab; that's the point. Order **searches**, and
+search the *likely* prisoner first: a prisoner with a bad record and a gnawed bed is the one to turn
+over. If searches keep coming up empty but weapons keep appearing, suspect a **bent warden** or a
+**gang** resupplying them (below). See [Concealment & Intake](contraband/Concealment-and-Intake.md).
+
+**Where is all this contraband coming from? I keep searching!**
+Three doors: prisoners **make** it (from their cell's own furniture), a **bent warden** smuggles it in,
+or a **gang** moves it from a stashed member to a searched one. Deny the materials (barer cells), watch
+your wardens, and **segregate** gang rivals so the network can't reach across the wing.
+
+**One of my wardens is corrupt / letting things through.**
+Warden corruption is a hidden disposition — a greedy or low-conduct colonist makes a leakier warden and
+may even smuggle. You can't get a clean readout, so if a wing stays dirty no matter how you search,
+rotate who wardens it. See [Corruption](contraband/Corruption.md).
+
+---
+
+## Prisoners who won't reform
+
+**I'm warding a prisoner but their reform isn't moving.**
+Reform only moves when a warden actually runs **rehabilitation** sessions — assign a warden to the
+prisoner and let them work. A **better cell** (more impressive) and a **higher-Social** warden reform
+faster; a bare cell and a rookie crawl. Don't leave a flagged prisoner untended: **neglect hardens**
+them. See [Rehabilitation](corrections/Rehabilitation.md).
+
+**A prisoner is "prisonized" / getting worse the longer I hold them.**
+Harsh **discipline** (solitary) raises the colony's order but **hardens** the prisoner — held long and
+handled roughly, they turn more dangerous, not less. If you want them out reformed, counsel more and
+discipline less. Discipline is a tool for *order*, not for *rehabilitation*. See
+[Discipline & Reform](corrections/Discipline-and-Reform.md).
+
+**How do I actually release a reformed prisoner?**
+Set their interaction mode to **Parole**. They go free when their **reform** is high enough **and** their
+**security grade** is low enough (a Supermax pawn won't parole). With Ideology, an execution-happy
+ideoligion sets a *high* bar (paroles rarely); an execution-abhorring one lets them out readily. A
+"Ready for parole" alert tells you when one qualifies. See [Parole](corrections/Parole.md).
+
+---
+
+## Classification & housing
+
+**I got a "dangerous prisoner unsecured" alert.**
+A high-grade prisoner (Maximum/Supermax) is being held somewhere too weak for their grade — in the open,
+or sharing a cell. Move them to a stronger wing. Place a wall-mounted **security marker** to grade a
+whole cell block at once, then the game knows which prisoners are misplaced. See
+[Classification](corrections/Classification.md).
+
+**A prisoner is miserable and I don't know why.**
+Two common Institution causes: they're **caged with a dangerous cellmate** (cell-safety mood hit — give
+them a solo cell) or they're on a **Lockup** schedule with no recreation. Give dangerous prisoners their
+own cells and hand prisoners some **Yard** time. See [Regime](corrections/Regime.md).
+
+---
+
+## Colony crime (Policing layer)
+
+**My own colonists are committing crimes now!**
+That's the **Policing** layer — colonists offend on the same propensity spectrum as everyone else, more
+often when they're mistreated, dangerous by nature, or living in a big anonymous colony. Keep colonists
+happy and the colony tight and it's rare. If you don't want colony crime at all, turn off the
+**Policing** toggle and the rest of the suite keeps working. See [Policing](policing/Policing.md).
+
+**A crime happened but no one was caught.**
+Witnesses and a **constable's** investigation accrue evidence over time before a culprit is named — give
+it a few days and assign someone capable to police work. Not every crime is solved. See
+[Policing](policing/Policing.md).
+
+**I don't want to arrest my star colonist over a petty theft.**
+You often won't have to — arrests are **weighed**: a valuable colonist and a minor crime tips toward
+letting it slide, and a small colony (or no free prison bed) won't arrest at all. And a disposed culprit
+may **resist** the arrest and try to break out.
+
+**A riot broke out!**
+The colony's **climate of order** collapsed. Order falls when crime goes unanswered and rises with
+**visible justice** — arrests and discipline. Riots only catch when order is already low, so the fix is
+to stop letting crime pay: catch and punish, and order recovers. See [Deterrence](policing/Deterrence.md).
+
+**Why does punishing one prisoner seem to calm the whole colony?**
+By design — the order climate feeds back into **everyone's** disposition. Catching and punishing one
+pawn deters the rest a little; letting crime slide emboldens them. That feedback is the whole point of
+the suite. See [Deterrence](policing/Deterrence.md).
+
+---
+
+## Gangs
+
+**A gang formed in my prison.**
+Gangs are a **symptom of a badly-run colony** — disposed prisoners band together along ties they already
+share. The counter-play is the rest of the suite: **segregate** rivals into different wings (a network
+whose members can't reach each other is starved), keep prisoners reformed, and don't let contraband
+flow. A well-run colony grows few gangs, if any. See [Joining](gangs/Joining.md) and
+[Affiliations & Segregation](gangs/Affiliations-and-Segregation.md).
+
+**Two prisoners keep fighting.**
+Rival-gang brawls are booked as **crimes** — they land on the attacker's record and erode the colony's
+order, so they matter beyond the moment. Segregating the rivals is how you stop it. See
+[Rivalry & Fights](gangs/Rivalry-and-Fights.md).
+
+---
+
+## Psychiatric care (Ward layer)
+
+**A prisoner broke mentally — I'd rather treat them than punish them.**
+Commit them to the **Ward**: sustained counselling reduces the disorder that broke them and builds a
+recovery track toward **discharge**. It's the other door out of the prison — recovery instead of
+punishment. Don't neglect a committed patient, or they deteriorate. A **sedative** can calm a patient
+who's about to break. See [Commitment](ward/Commitment.md).
+
+---
+
+## Settings & compatibility
+
+**This is too much / I only want part of it.**
+Every layer is independent. Open **Options → Mod Settings → Institution** and untick any of Contraband,
+Policing, Corrections, Gangs, or Ward. The one you turn off goes inert immediately; the rest still work.
+
+**Does it play nice with other prison / psychiatry mods?**
+Yes — Institution rides vanilla's own prisoner rail and is tested against the popular psych/prison mods.
+It extends rather than replaces, so it coexists with the mods that own the parts it doesn't. Ward in
+particular is built to sit alongside Hospitality, Psychology, Rim Disorders and friends.
+
+**Do I need anything else?**
+Just **[Harmony](https://steamcommunity.com/sharedfiles/filedetails/?id=2009463077)**. The shared Core
+engine ships inside the mod. **Foul Play** (a separate mod) bridges in if you also run it.
+
+---
+
+*Back to the [Wiki home](Home.md).*

Home.md

@@ -1,93 +1,104 @@
-# Institution: Ward
+# Institution — Wiki
 
-**Involuntary psychiatric commitment for RimWorld 1.6 — the third pawn state, neither free nor guilty.**
+*Prison Architect in RimWorld. One install, six toggleable layers, over one shared engine.*
 
-> **The psychiatric-care layer of the [Institution](https://git.onetick.ninja/flan/rimworld-institution)
-> suite.** Ward runs on Core's shared treatment engine and ships bundled in the single Institution
-> install with a toggle of its own; it still installs standalone (needing only Institution: Core and
-> Harmony). Once a separate sister mod, now folded in.
+> **Every pawn has a criminal propensity on a spectrum — nature (traits) × nurture (mood,
+> mistreatment, treatment) — and the colony can police it.**
 
-RimWorld gives a person exactly two places to stand: **colonist**, or **prisoner**. There is no
-third state for someone who is neither free nor guilty. Out of the box you cannot commit anyone. A
-colonist breaks, wanders off, punches a wall, recovers on their own, and goes back to hauling steel
-as though nothing happened. Mental breaks are episodic and amnesiac — nothing persists, nothing is
-*done* about them.
+That one sentence is the whole suite. Colonists, prisoners, and slaves drift toward crime on a
+continuous spectrum; a policing-and-corrections machine discovers, catches, weighs, punishes, reforms,
+treats, and releases them — and catching one pawn changes the disposition of the rest.
 
-Ward adds the missing state, and the room to put it in. A colonist you arrest can be set to
-**psychiatric care**. Wardens counsel them at a **treatment station**. A room with prisoner beds
-and a treatment station is a **psychiatric ward**, not a prison cell. Treatment lowers the patient's
-mental-break threshold while it lasts — and it fades, so it has to be *sustained*. A ward you don't
-staff is worse than no ward at all.
+**Institution** is the single mod that ships all of it — every layer bundled into one install with a
+**checkbox per layer** (all on by default), so you run as much or as little of the suite as you like.
+
+> **New to it?** The **[FAQ](FAQ.md)** covers what to do when the mod throws something new at you — an
+> escape tunnel, a gang in the wing, a riot, a prisoner who won't reform, a "dangerous prisoner
+> unsecured" alert.
 
 ---
 
-## The third state RimWorld doesn't have
+## The gameplay loop
 
-The reason "commit a colonist" isn't a stock button is simple: vanilla only knows two kinds of held
-person — a free colonist and a prisoner. There's no built-in slot for someone who is neither free nor
-guilty, which is why other mods that keep a not-quite-colonist around (like *Hospitality* and its
-guests) have to work so hard to maintain them.
+The suite is a closed loop, and each turn of it lives in a different layer — mirroring the real
+separation of powers: police, (courts,) prison, parole.
 
-**Ward takes the cheap road.** A committed pawn *is* a prisoner — arresting your own colonist already
-does that. Ward just adds a new **way to handle** that prisoner: a "psychiatric care" mode you toggle
-on, sitting alongside vanilla's recruit / convert / release options. Nothing exotic — it's the same
-kind of custom prisoner mode other prison mods already add.
+1. **Disposition** *(Core)* — every pawn carries a seeded propensity: *would this one do it?*
+2. **Crime** *(Policing)* — free colonists offend on that spectrum (rare in a small, tight,
+   well-deterred colony), with visible consequences — theft, vandalism, assault — that fray
+   relationships.
+3. **Detection** *(Policing)* — witnesses and a **constable** work an open case until the culprit is named.
+4. **The weighed arrest** *(Policing)* — an arrest is made only when the crime is grave enough to
+   justify losing the pawn and the colony can afford to hold a prisoner; the disposed **resist**, and a
+   subdued resister is taken in. *(A future **Judiciary** layer — a court that tries and sentences —
+   is reserved to sit here, between arrest and imprisonment; today the arrest imprisons directly.)*
+5. **Contraband** *(Contraband)* — once held, a pawn conceals and improvises: shivs, brews, tunnels
+   under the perimeter, all countered by warden search — and a bent warden who smuggles for them.
+6. **Gangs** *(Gangs)* — held pawns organise into contraband economies: joining by disposition,
+   smuggling networks, rivalry, fights that book as crimes.
+7. **Corrections** *(Corrections)* — a warden **rehabilitates** a prisoner: counselling sessions move a
+   **reform** score and raise the colony's climate of **order** (classification re-grades as reform
+   rises), that order feeds back into everyone's disposition, and a **parole** alert releases the
+   genuinely reformed back into the colony. Neglect a flagged prisoner and they harden.
+8. **Treatment** *(Ward)* — the other door: a prisoner committed for **psychiatric care** rather than
+   punished. Counselling reduces the disorder that broke them and builds a recovery track toward
+   discharge; neglect a committed patient and they deteriorate.
 
-So committing someone is entirely ordinary from the game's point of view:
-
-- **psychiatric care** — a new prisoner interaction mode you switch on
-- **the psychiatric ward** — a new room role a cell earns once it holds a treatment station
-- **counselling** — a new warden job, handled like any other warden work
-- the **treatment station**, the **recovery**, the **neglect** — new content layered on top
-
-Because Ward *adds* things rather than rewriting how vanilla prisoners behave, it sits quietly next to
-the popular psych and prison mods instead of fighting them. Which mods, and why, is on the
-**Compatibility** page.
+Steps 7 and 8 close the loop back onto step 1: catching, punishing, reforming, or treating one pawn
+moves the colony's climate of order, which bends the disposition of everyone still deciding whether
+crime pays here.
 
 ---
 
-## Riding the prisoner rail (why the suite cares)
+## The six layers
 
-The choice that makes Ward *cheap* also makes it *interesting* inside the wider Institution suite. A
-committed patient is a genuine vanilla prisoner. That means they're a **held pawn** in exactly the
-sense the rest of the suite understands: someone who can be searched, and who can conceal and
-improvise contraband. A patient in a psych ward can hoard a shiv or brew something foul in a smuggled
-vessel, because the contraband, search, corruption and gang systems already work on any held
-prisoner — and a ward patient is one, for free.
+Each is a separate repo and DLL, bundled here behind a toggle. Every layer defaults **on**; turning
+one off disables its systems in place without uninstalling anything.
 
-**And re-labelling a cell as a ward never lets anyone out.** A ward is a prison cell that also happens
-to be a ward — the two roles coexist. Containment, food delivery, and prison breaks all keep working
-exactly as they did before you built the station.
+| Layer | Toggle | What it adds | Wiki |
+|---|---|---|---|
+| **Core** | *(always on — the engine)* | propensity, the criminal record, secured context, the shared **treatment engine**, the deterrence seam | [Core](core/Home.md) |
+| **Contraband** | Contraband | concealment & intake, improvised shivs, Prison-Architect tunnels, warden search, warden corruption | [Contraband](contraband/Home.md) |
+| **Policing** | Policing | colony crime on the spectrum, witnesses, a constable, the weighed arrest, the deterrence feedback loop, prison riots, recidivism alerts | [Policing](policing/Home.md) |
+| **Corrections** | Corrections | classification (with whole-wing markers), discipline & reform, **rehabilitation** + parole, regime (recreation/visitation/cell-safety) | [Corrections](corrections/Home.md) |
+| **Gangs** | Gangs | gangs as contraband economies — joining, smuggling networks, rivalry, fights-as-crime | [Gangs](gangs/Home.md) |
+| **Ward** | Ward | psychiatric care — treatment, recovery, discharge, ward neglect, sedation | [Ward](ward/Home.md) |
+
+**Policing** and **Corrections** are separate layers — the enforcement half and the prison half of the
+former *Justice* module, split along the separation of powers. Policing has its own toggle because
+colony crime is a large behavioural change: a player can run the prison (Corrections) without their own
+colonists committing crimes. Corrections depends on Policing for the shared climate of order.
 
 ---
 
-## Wiki index
+## Why one Core, many layers
 
-| Page | What's on it |
-|---|---|
-| **Home** (this page) | What Ward is, the third-state problem, the suite |
-| **Commitment** | How commitment works in play: the care mode, the station, the ward room, the warden's job, treatment, recovery, neglect, and how it stacks with recruitment — with the real numbers |
-| **Compatibility** | Which popular psych and prison mods Ward plays nicely with, and why it doesn't fight them |
+The suite runs on a small **Core** that owns exactly what every layer must agree on — *is this pawn
+dangerous?*, *what have they actually done?*, *what hold are they under?* — plus two shared services:
+the **treatment engine** (Ward's psychiatric care and Corrections' rehabilitation point the same loop
+at different states) and the **deterrence seam** (a neutral hook Policing fills so the order-climate
+feedback runs *through* Core without Core ever depending on the policing layer). A future **Judiciary**
+layer will slot in through the same style of Core seam — a *sentence* on the criminal record that
+Policing writes a default of today and a court would fill tomorrow.
+
+Everything else builds up from there: Contraband, Policing, and Corrections on Core (Corrections also
+on Policing); Gangs on Core + Contraband + Policing; Ward on Core. Cross-layer integrations that aren't
+hard dependencies stay soft — a feature lights up if its sibling is present and the loop still closes
+without it. That is what keeps the suite genuinely modular: this aggregate is a convenience, not a merge.
 
 ---
 
-## Part of the Institution suite
+## Requirements & install
 
-A set of RimWorld 1.6 mods about what an institution does to the people inside it. Each mod stands
-alone as an install; together they interlock into one system — colonists and prisoners drift toward
-crime on a spectrum of nature × nurture, and a policing/justice layer discovers, catches, punishes,
-reforms, or paroles them. Ward's psychiatric ward is a secure context where a committed patient can
-conceal and improvise contraband exactly as a prisoner can, because they ride the same prisoner rail.
+- **RimWorld 1.6.**
+- **[Harmony](https://steamcommunity.com/sharedfiles/filedetails/?id=2009463077)** — required (the
+  suite's Harmony-using code is Corrections' prisoner-recreation patch and Ward's).
+- Install **Institution**, enable Harmony, and load Institution after it. That is the whole suite in
+  one mod; open the settings to toggle any layer.
 
-| Mod | What it is |
-|---|---|
-| **Institution: Ward** (this) | Involuntary psychiatric commitment — the third pawn state, neither free nor guilty. |
-| **Institution: Core** | The shared engine — propensity (nature × nurture), the criminal record, secured context. |
-| **Institution: Contraband** | The physical smuggling loop — conceal, improvise shivs, dig Prison-Architect tunnels, warden search, warden corruption. |
-| **Institution: Justice** | Corrections & policing — classification, deterrence, discipline, parole, regime. |
-| **Institution: Gangs** | Gangs as contraband economies — joining, smuggling networks, rivalry, fights-as-crime. |
-| **Foul Play** | The vessel + substance + throw framework, and the "Piss Nuke" flagship; bridges to Core + Contraband when both are present. |
-
-Reference sibling mods by name — the mods are separate repositories and cross-repo links break.
+The standalone **[Foul Play](https://git.onetick.ninja/flan/rimworld-foulplay/wiki)** framework is a
+separate install that bridges into the suite when both are present.
 
 ---
+
+*The **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs · Ward.*

contraband/Compatibility.md

@@ -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.*

contraband/Concealment-and-Intake.md

@@ -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.*

contraband/Corruption.md

@@ -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.*

contraband/Home.md

@@ -0,0 +1,126 @@
+# Institution: Contraband
+
+*Prisoners get hold of things they should not have. Wardens turn the cell over looking for them.*
+
+This is the player-facing wiki for **Institution: Contraband**, a RimWorld 1.6 mod. It documents
+every mechanic with the real numbers, explains why each one works the way it does, and tells you how
+to play with them — and against them.
+
+> **Note on scope.** Contraband was recently *split*. It is now one thing: the **physical smuggling
+> 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.**
+
+Contraband is the half of that sentence you can *hold in your hand*. A propensity is abstract until a
+disposed prisoner files a blade off his bunk, palms a twist of yayo on the way into a cell, or starts
+digging. Contraband is where the spectrum becomes an object with edges.
+
+## Vanilla built the demand and forgot the supply chain
+
+RimWorld already ships a fully-built junkie. Raiders spawn addicted and carrying combat drugs. You
+down one, capture strips everything, and now withdrawal grips them in the cell. A prisoner already
+*seeks* a drug on their own, and already *ignores* the forbidden flag inside their own cell.
+
+Put a drug within reach of an addicted prisoner and the base game makes them take it. Today. The
+consumer, the craving, the reach, the ignore-forbidden — all of it already works.
+
+What does **not** exist is any answer to two questions:
+
+| 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 |
+|---|---|---|
+| **Intake** | A captive hides the small contraband they walked in with | [Concealment and Intake](Concealment-and-Intake.md) |
+| **Improvise** | Whittle a shiv from the cell's own furniture | [Improvised Weapons](Improvised-Weapons.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) |
+
+And because every guard is a person with their own diligence and their own price, the search is only
+as good as who you send — see **[Corruption](Corruption.md)**.
+
+## How everything is contraband without a list
+
+Contraband names no items. It recognises three kinds of thing:
+
+1. **Anything explicitly marked as contraband** — the opt-in, with pluggable behaviour a mod can
+   supply.
+2. **Every drug** — vanilla's, Vanilla Expanded's, mods that don't exist yet. Hard drugs conceal
+   better (0.75 vs 0.5).
+3. **Every weapon** — how well it hides, and where, is decided by its **mass**. A knife rides on the
+   body; a heavy gun goes under the floor; a minigun (over 10 kg) hides nowhere.
+
+It reads the item's own stats rather than editing anything. Nothing changes another mod's items.
+Details in [Concealment and Intake](Concealment-and-Intake.md) and [Compatibility](Compatibility.md).
+
+## 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.
+
+| Mod | Owns | Depends on |
+|---|---|---|
+| **Institution: Core** | propensity, criminal record, secured context | base game |
+| **Institution: Contraband** (this) | concealment, intake, shivs, tunnels, search, corruption | Core |
+| **Institution: Justice** | classification, deterrence, discipline, parole, regime | Core |
+| **Institution: Gangs** | gangs as contraband economies | Core, Contraband, Justice |
+| **Foul Play** | vessel + substance + throw framework; the Piss Nuke; bridges its carboy in as contraband | standalone |
+| **Ward** | a ward prison mode | — |
+
+---
+
+*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
+Ward. Each stands alone; together they interlock.*

contraband/Improvised-Weapons.md

@@ -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.*

contraband/Tunnels.md

@@ -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.*

contraband/Warden-Search.md

@@ -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.*

core/Criminal-Record.md

@@ -0,0 +1,102 @@
+# 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.*

core/Home.md

@@ -0,0 +1,88 @@
+# Institution: Core — Wiki
+
+*The shared foundation of the **Institution** suite: a set of RimWorld 1.6 mods about what an
+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
+see** — no items, no jobs, no new menus. It sits completely quiet until another Institution mod is
+installed on top of it. You install Core only because something else asks for it.
+
+This wiki explains what that hidden engine actually does once a mod above it puts it to work — down to
+the exact numbers, because knowing how the numbers move is half the fun of running a prison.
+
+---
+
+## The one idea
+
+> **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
+continuous spectrum; a policing and justice layer discovers, catches, punishes, reforms, or paroles
+them. Core is where the *spectrum* itself lives — before anyone is caught, before there is a record to
+read, before there is a warden to search them.
+
+## Why a shared engine
+
+The propensity idea didn't start out abstract. It grew up twice, in two different mods: one deciding
+which drunk, miserable pawn starts a mess, and one deciding which prisoner whittles a shiv the moment a
+door opens. Both were asking the same real question — *would **this** pawn do it?* — and each answered
+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
+system all read one disposition engine, they agree about who is dangerous instead of each judging it
+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
+nothing else:
+
+| Pillar | Answers | Page |
+|---|---|---|
+| **Propensity** | *Would this pawn do it?* (nature × nurture) | [Propensity](Propensity.md) |
+| **Criminal record** | *What has this pawn actually done?* (one history per pawn) | [Criminal Record](Criminal-Record.md) |
+| **Secured context** | *What kind of hold is this pawn under, and who may search them?* | [Secured Context](Secured-Context.md) |
+
+The distinction between the first two is the spine of the whole design: **propensity is suspicion, a
+record is fact.** Propensity says "this pawn *seems* dangerous"; a record says "this pawn *has*
+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
+
+- **[Propensity](Propensity.md)** — nature × nurture in full: the trait-weight table, the nurture
+  multiplier ladder, the disposition formula with worked examples, and why each pawn's roll is fixed
+  rather than re-rolled.
+- **[Criminal Record](Criminal-Record.md)** — everything a record remembers, who fills in each part,
+  how it persists across saves, and why *reform* is the pivot of the whole suite.
+- **[Secured Context](Secured-Context.md)** — the Free / Prisoner / Slave kinds, what counts as
+  "held" versus what counts as "able to hide something," and why the suite keys off this instead of
+  "is a prisoner."
+- **[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
+  toward discharge. Ward's psychiatric care and Justice's reform run on this one engine.
+- **[Modder API](Modder-API.md)** — the "for modders" page: the tools any mod can call to build on
+  Core. Players can skip it.
+
+## The suite
+
+Each mod stands alone as an install; together they form one system. Core sits underneath everything
+else.
+
+| Mod | What it adds | Needs |
+|---|---|---|
+| **Institution: Core** (this) | the propensity / record / context engine | base game only |
+| **Institution: Contraband** | concealment, improvised shivs, tunnels, warden search, warden corruption | Core |
+| **Institution: Justice** | classification, deterrence, discipline, parole, regime, and **policing** (colony crime → weighed arrest) | Core, Harmony |
+| **Institution: Gangs** | gangs as contraband economies: joining, smuggling, rivalry, fights-as-crime | Core, Contraband, Justice |
+| **Institution: Ward** | psychiatric care — a prisoner treated, not punished, on Core's treatment engine | Core, Harmony |
+| **Foul Play** | the vessel + substance + throw framework, home of the "Piss Nuke" | standalone; bridges to Core + Contraband |
+
+## 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.*

core/Modder-API.md

@@ -0,0 +1,238 @@
+# 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.*

core/Propensity.md

@@ -0,0 +1,212 @@
+# 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.*

core/Secured-Context.md

@@ -0,0 +1,88 @@
+# 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.*

core/Treatment-Engine.md

@@ -0,0 +1,94 @@
+# 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.*

corrections/Classification.md

@@ -0,0 +1,115 @@
+# Classification
+
+*The intelligence layer over the wings you already build by hand.*
+
+You already build a minimum wing and a max block. You already put the psychopath behind steel and the
+teenage pickpocket behind a wooden door. Classification does not replace those walls, cells and locks —
+it answers the question vanilla never does: **who belongs where.** It reads the one shared record every
+part of the suite writes to and turns it into a single verdict, so the crime system, the search, the
+escape and the classifier all agree on how dangerous a pawn is, because they read the same number.
+
+Grade drives everything downstream: search frequency, privileges, escape risk, and — critically —
+parole eligibility ([Parole](Parole.md) gates on grade).
+
+> The isolation *toll* of a max/solitary placement is Prisoner Realism's (good) sim. Corrections only
+> decides the placement.
+
+---
+
+## The tiers
+
+Every held pawn falls into one of four security grades, low to high — the tiers you already build,
+named:
+
+| Grade | Risk score | Reading |
+|---|---|---|
+| **Minimum** | below 0.35 | Barely a disposition, clean record. Open dorm, light watch. |
+| **Medium** | 0.35 – 0.79 | A real record or a real nature. Proper cell, routine search. The parole ceiling. |
+| **Maximum** | 0.80 – 1.49 | Repeat offender or proven flight risk. Steel, solitary door, frequent search. |
+| **Supermax** | 1.5 and up | The headline cases. Escapes plus crimes plus a dark nature. Never let them near a wall. |
+
+Note the ceiling at **Medium**: [Parole](Parole.md) will only consider a pawn graded Medium or below.
+Grade is therefore not just a placement hint — it is the gate a pawn has to fall back through before
+they can be released.
+
+---
+
+## The risk score
+
+Risk is a number from 0 to about 3: baseline disposition, plus everything on the record, minus reform
+earned. Each thing a prisoner has done adds a fixed amount:
+
+| What it counts | Adds to risk | Why this weight |
+|---|---|---|
+| **Nature** (0 to 1) | nature × 0.5 | Disposition alone can carry a pawn to Medium (nature 0.7+), but never past it on its own. Character is a suspicion, not a conviction. |
+| **Each escape attempt** | +0.35 | The heaviest per-event term. A pawn who *runs* is the one who ends up armed in your base. One attempt is worth nearly two crimes. |
+| **Each crime committed** | +0.20 | The staple. Steady, cumulative. |
+| **Each time caught** | +0.15 | Caught contraband is worse than merely suspected. |
+| **Each contraband item made** | +0.10 | The lightest term — making a shiv is common; escaping with one is not. |
+| **Reform earned** | up to −0.4 | The only thing that *lowers* the grade. At most −0.4, since reform caps at 1.0. |
+
+The total is never allowed below zero.
+
+Two facts fall out of the numbers, and both matter for how you play:
+
+- **Searching a prisoner does not raise their risk.** Only *finding* something does — a search that
+  turns up nothing costs the prisoner no grade. Search freely.
+- **Reform can shift at most 0.4 of risk.** At full reform (1.0), the downgrade is −0.4. So a pawn
+  whose record *without reform* already totals 1.2 or more can never fall to Medium (below 0.8) no
+  matter how thoroughly they reform — and therefore can **never be paroled**. A prolific offender is a
+  life sentence. You will hold them, work them, or execute them; you will not release them. This is a
+  deliberate property of the weights, not an accident.
+
+---
+
+## Worked example — grading a record
+
+**Bram**, an Abrasive raider, has a nature of 0.20. He has three crimes, one escape attempt, was caught
+twice, made two shivs, and has not been reformed. Add it up:
+
+| Source | Contribution |
+|---|---|
+| nature 0.20 × 0.5 | 0.100 |
+| 1 escape × 0.35 | 0.350 (the headline) |
+| 3 crimes × 0.20 | 0.600 |
+| caught twice × 0.15 | 0.300 |
+| 2 shivs × 0.10 | 0.200 |
+| no reform | 0.000 |
+| **total** | **1.550** → Supermax |
+
+Now treat him. Say patient handling and good conduct lift his reform to 0.40. That subtracts
+0.40 × 0.4 = 0.16, dropping his risk to **1.39 → Maximum.** He falls a band.
+
+But notice: his reform-*less* risk is 1.55, well above 1.2. Even at perfect reform (1.0) he lands at
+1.55 − 0.40 = 1.15 — still Maximum. **Bram is beyond parole for the rest of his life.** His record
+decided that, not his disposition.
+
+Contrast **Cass**, a Kind pickpocket whose gentle nature floors her nature term at 0. She has one
+crime, was caught once, no escapes, no contraband, no reform yet. Her risk is
+(1 × 0.20) + (1 × 0.15) = **0.35 → Medium**, exactly on the line.
+
+Give Cass the standard treatment up to reform 0.30. That subtracts 0.30 × 0.4 = 0.12, dropping her to
+**0.23 → Minimum.** Cass is now Minimum, and — being Medium-or-below with reform at least 0.30 —
+**paroleable.** Same institution, two futures, and the record told you which was which before you had
+to guess.
+
+---
+
+## How to play with grades
+
+- **Segregate by grade, not by vibe.** Sort your cells to the four bands and put a pawn where their
+  score, not your hunch, says. The whole suite reads the record; you can too.
+- **Escapes are the alarm.** One escape attempt (+0.35) will jump a middling pawn a band. If a pawn
+  crosses into Maximum after a break attempt, believe it — treat them as the flight risk the number
+  says they are.
+- **A clean nature is not a clean record.** A Kind pawn who has escaped twice still grades Maximum;
+  disposition is only half the score.
+- **Watch the parole ceiling.** If you intend to release someone, keep their reform-less risk under
+  1.2 — mostly that means limiting how deep their record gets *before* you start treating them. A pawn
+  you let rack up escapes and catches has sentenced themselves.
+- **Reform is the only lever that lowers a grade.** See [Discipline & Reform](Discipline-and-Reform.md)
+  for how to move it, and [Parole](Parole.md) for where the grade gate lands.
+
+---
+
+*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs · Ward.*

corrections/Discipline-and-Reform.md

@@ -0,0 +1,111 @@
+# Discipline & Reform
+
+*Punishment as an action, with a self-complete payoff — and the seat of institutionalization.*
+
+> This page is the **numbers** — what a disciplinary act does to reform and order. What *drives* it in
+> play (a warden's rehabilitation sessions, and neglect that hardens) is [Rehabilitation](Rehabilitation.md).
+
+Punishment does two things at once, on two different axes:
+
+1. **It deters the colony.** Order seen to be done raises the climate of order for everyone: any act of
+   discipline adds **+0.12** to the colony's order. See [Deterrence](Deterrence.md).
+2. **It reshapes the punished.** A harsh hand *prisonizes* — the pawn hardens, reform falls, their
+   disposition climbs for good. A corrective hand *rehabilitates* — reform rises, their disposition
+   cools for good.
+
+Both effects belong to Corrections, so discipline is never inert. Prisoner Realism owns the passive
+*toll* of isolation (a good sim of how solitary *feels*); Corrections owns the *order* it produces and
+the persistent *shift* it leaves on the pawn. When both mods are present, PR's solitary deterioration
+deepens the felt experience on top — it does not replace this.
+
+---
+
+## The two hands
+
+Every disciplinary act moves the prisoner's **reform** score, in one of two directions:
+
+| The hand | Reform change | Meaning |
+|---|---|---|
+| **Harsh** | **−0.15** | Beatings, deprivation, the hard hand. Hardens — "prisonization." |
+| **Corrective** | **+0.10** | Correction, structure, rewarded good conduct. Rehabilitates. |
+
+Either way, the act also adds **+0.12** to the colony's order — the colony sees order done, whoever it
+was done to.
+
+Reform lives on the shared record, clamped between −1 and +1:
+
+| Reform | Reading |
+|---|---|
+| **+1.0** | Fully rehabilitated |
+| **0.0** | Untouched — as they came in |
+| **−1.0** | Fully hardened, institutionalized |
+
+Note the asymmetry: **harsh (−0.15) moves faster than gentle (+0.10).** It takes three corrective acts
+to build +0.30 of reform; two harsh acts to tear down −0.30. Damage is quicker than repair — as it
+should be.
+
+---
+
+## How reform becomes disposition
+
+Reform is not a status effect or a mood buff. It feeds straight back into a pawn's **disposition** —
+Core's underlying "would they act out?" multiplier — scaling their whole disposition up or down and
+keeping it there. The size of that scaling is set entirely by reform:
+
+| Reform | Disposition factor | Effect |
+|---|---|---|
+| −1.00 (hardened) | **1.500** | +50% more disposed — permanently |
+| −0.30 | 1.150 | +15% |
+| −0.15 (one harsh act) | 1.075 | +7.5% |
+| 0.00 | 1.000 | untouched |
+| +0.10 (one gentle act) | 0.950 | −5% |
+| +0.30 (parole threshold) | 0.850 | −15% |
+| +1.00 (rehabilitated) | **0.500** | −50% less disposed — permanently |
+
+Because reform is clamped between −1 and +1, the factor spans 0.5× to 1.5×. **This is the whole
+trick.** Institutionalization and recidivism are not a parallel mechanic bolted on the side — they are
+*one number the disposition already reads*. A hardened pawn is not flagged "recidivist"; they simply
+carry a negative reform that makes every "would they?" roll for the rest of their life come up hot.
+Discipline and Parole are what *move* reform; disposition only *reads* it — which is how
+institutionalization emerges without a second system.
+
+---
+
+## Worked example — two sentences
+
+Take a fresh prisoner with reform 0, badly kept: mood 0.30, held. Before any reform, their disposition
+is already running hot — a bad mood (×1.6) and a held-and-unhappy cell (×1.4) combine, and with the
+colony at baseline the pawn sits around **2.35× disposition**.
+
+**The hard hand.** You beat them into line — three harsh punishments take reform to −0.45. At that
+reform the disposition factor is 1.225, so their disposition is now 2.35 × 1.225 ≈ **2.88 — +22% hotter
+than when they arrived**, forever, independent of mood. You have made them more criminal, not less.
+This is prisonization: the sentence itself became the cause. (You did buy +0.36 of colony order along
+the way — order today, at the cost of the pawn's tomorrow.)
+
+**The corrective hand.** Instead you structure and reward — three gentle punishments *and* you fix
+their conditions (recreation, decent cell) so mood recovers to 0.55. Reform rises to +0.30, and the
+recovered mood drops the "badly kept" and "held-and-unhappy" penalties entirely. The disposition factor
+at +0.30 reform is 0.85, so their disposition is now roughly **0.89 — below neutral.** The same pawn who
+would have been 2.88 disposed is now 0.89. And at reform 0.30 with a low enough grade they have crossed
+the [Parole](Parole.md) threshold. Same institution, opposite outcomes — decided by which hand you used.
+
+---
+
+## How to play with discipline
+
+- **Harsh is a lever, not a punishment button.** It buys colony order *now* (+0.12) at the price of the
+  pawn's disposition *forever* (−0.15 reform → hotter disposition). Use it when you need the deterrence
+  and never intend to release the pawn — a Supermax lifer you are only ever going to hold.
+- **Gentle is how anyone gets out.** Parole needs reform 0.30 or higher; only the corrective hand
+  builds it. Three gentle acts is the floor.
+- **Damage compounds; repair is slow.** −0.15 vs +0.10 means a pawn you brutalize early is expensive to
+  bring back — and a hardened pawn commits more crime, which sinks the climate, which makes *everyone*
+  worse. Don't harden pawns you might want later.
+- **Conditions and discipline stack.** Reform shifts disposition permanently; mood, neglect and
+  deterrence shift it live (see [Regime](Regime.md) and [Deterrence](Deterrence.md)). A reformed pawn
+  in a well-run wing is calm on two axes at once.
+
+---
+
+*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs · Ward.*

corrections/Home.md

@@ -0,0 +1,49 @@
+# Institution: Corrections
+
+*The prison layer — what the colony **does** with a pawn once they are in custody — of the
+**Institution** suite of RimWorld 1.6 mods.*
+
+Vanilla RimWorld's prisoners are interchangeable mood-boxes; a "maximum security" wing is a decoration
+the sim never acknowledges, and a warden's work never changes who a pawn becomes. **Corrections turns
+the prison into a regime you run** — it grades every held pawn from what they have actually done,
+tracks a *reform* score that decides whether a sentence hardens or heals a prisoner, gates release on
+it, and gives prisoners the recreation need vanilla flatly denies them.
+
+---
+
+## The pages
+
+| Page | What it covers |
+|---|---|
+| **[Classification](Classification.md)** | Grades held pawns Minimum..Supermax from a risk score over their record; wall-mounted security markers grade a whole wing; misplacement alerts. |
+| **[Discipline & Reform](Discipline-and-Reform.md)** | Punishment moves the reform score — harden ("prisonized") vs. rehabilitate. The seat of institutionalization and recidivism. |
+| **[Rehabilitation](Rehabilitation.md)** | The warden work that drives the arc: counselling sessions move reform and colony order, a parole alert and release, neglect that hardens. |
+| **[Parole](Parole.md)** | Release a reformed, low-grade prisoner as a free colonist; with Ideology, your execution stance sets the bar. |
+| **[Regime](Regime.md)** | Prisoner recreation (Yard/Lockup schedule via Prison Labor's timetable), visitation, cell-safety. |
+
+---
+
+## One shared record
+
+Corrections keeps no crime history of its own. Every held pawn carries a single record that
+**Institution: Core** maintains — the same record Contraband, Policing, and the gang systems all read
+and write. Discipline and Parole write the *reform* and *pardon* onto it; classification grades and the
+release gate read back over every counter its siblings feed in. Reform and rehabilitation run on Core's
+shared treatment system, the same one Ward's psychiatric care uses — so a prisoner's whole arc, from
+first crime to parole, is one continuous history rather than a pile of separate flags.
+
+---
+
+## Requirements & load order
+
+- **RimWorld 1.6**
+- **Institution: Core** — required (the disposition, record, and treatment systems)
+- **Institution: Policing** — required (the shared climate of order: discipline and rehab nudge it, the
+  inspect pane reads it)
+- **Harmony** — required (Regime's prisoner-recreation feature)
+- Load **after** Core, Policing, and Harmony.
+
+---
+
+*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs
+· Ward. Split out of the former Institution: Justice.*

corrections/Parole.md

@@ -0,0 +1,115 @@
+# Parole
+
+*Release, driven by what the pawn has become.*
+
+> This page is the release **decision**. The warden work that acts on it — the "Ready for parole" alert
+> and the release that frees a parolee back into the colony — is [Rehabilitation](Rehabilitation.md).
+
+Parole is the end of the arc, and it is deliberately a *decision*, not a mechanic that rebuilds the
+game's release flow. It asks one question — **is this pawn ready?** — and answers it from two things
+already on the record: the reform the sentence earned (or failed to earn), and the grade the record
+warrants.
+
+> The *return* outcome — a grateful ally, a vengeful raider — is Prisoner Realism's Recidivism, a good
+> sim Corrections does not rebuild. Corrections' mirror is the parolee who **stays** and may reoffend,
+> carrying their record into the colony.
+
+---
+
+## The gate
+
+A prisoner can be paroled only when **all three** of these hold:
+
+| Condition | Threshold | Why |
+|---|---|---|
+| Not already pardoned | never released before | Release is one-way; you can't re-parole. |
+| Genuinely reformed | reform 0.30 or higher | Proof the sentence *healed* rather than hardened. Three corrective acts minimum. |
+| Low enough grade | grade Medium or below (risk under 0.8) | Reform of attitude is not enough — the *record* must have cooled to something you'd let out. |
+
+A pawn with **no record at all** is releasable trivially (there is nothing to hold them). Everyone else
+has to earn all three.
+
+The grade gate and the reform gate interact in a way worth internalizing. Because reform subtracts at
+most 0.4 from risk ([Classification](Classification.md)), a pawn whose reform-*less* risk is 1.2 or more
+can never reach Medium — so **no amount of reform will ever parole a prolific offender.** Parole is for
+pawns whose record stayed shallow enough that treatment can pull them back under the ceiling. Let a pawn
+rack up escapes and catches and you have quietly converted them into a lifer, whatever their attitude.
+
+---
+
+## Release
+
+Releasing a parolee marks a **pardon** on their record. Vanilla does the actual freeing; the pardon is
+Corrections' memory that this pawn was let out after genuine reform, so reintegration can grant a clean
+slate and the pawn won't be offered for parole twice. A modest faction-goodwill / relationship nudge for
+a well-handled release is the immediate payoff.
+
+---
+
+## The whole arc
+
+The pawn moves through every stage in turn, and each one writes the record the next one reads:
+
+| Stage | Where it lives | What moves | What's recorded |
+|---|---|---|---|
+| 1. Crime | [Deterrence](Deterrence.md) | Climate −0.08; the colony runs hot | a crime, and when it happened |
+| 2. Caught & held | [Classification](Classification.md) | A grade is assigned from the record | reads every counter |
+| 3. Discipline | [Discipline](Discipline-and-Reform.md) | Reform moves ±; climate +0.12 | reform |
+| 4. Reform | [Discipline](Discipline-and-Reform.md) → Core | Disposition cools as reform rises | reform (read by disposition) |
+| 5. Regrade | [Classification](Classification.md) | Reform subtracts risk; grade falls | reads reform |
+| 6. **Parole** | this page | Gate opens at reform 0.30 **and** grade Medium or below | reads reform and pardon; sets pardon |
+
+It is a loop, not a line: the crime that opens stage 1 also cools the colony's climate, which the *next*
+pawn's disposition reads — so one pawn's whole sentence is faintly present in every other pawn's odds.
+
+---
+
+## Worked example — a sentence that ends in release
+
+**Cass**, a Kind pickpocket whose gentle nature floors her nature term at 0. She arrives with one crime,
+caught once, no escapes, no contraband, no reform yet. Her risk is (1 × 0.20) + (1 × 0.15) = **0.35 →
+Medium.** She is already Medium-or-below, so the *grade* gate is met — but her reform is 0, so she is not
+yet releasable.
+
+You give her the corrective hand three times (structure, rewarded conduct) and fix her cell so she
+isn't stewing. Reform rises to 0.30, which subtracts 0.30 × 0.4 = 0.12 from her risk, dropping her to
+**0.23 → Minimum.** Now all three gates are met — reform at least 0.30, Minimum is below Medium, and
+she's never been pardoned — so **Cass is paroleable.** Pardon her and she walks.
+
+Contrast **Bram** from the Classification page, whose reform-less risk of 1.55 keeps him at Maximum even
+at full reform — the grade gate never opens for him, so he can never be paroled. Two prisoners, the same
+treatment, and the record decides which one you can ever let go.
+
+---
+
+## A note on record cleanup
+
+A pawn with a completely empty record — no crimes, no escapes, no contraband, no catches, no reform, no
+pardon — is forgotten on save/load (Core prunes blank and dead-pawn records). A *pardoned* pawn is
+therefore **not** empty, and their record persists: the pardon is remembered. This is why a released
+parolee who stays and reoffends still carries their history — Corrections does not forget that they were
+once let out.
+
+---
+
+## Ideology-flavoured thresholds
+
+Precepts layer on top of this baseline, not under it: an execution-favouring ideoligion paroles rarely,
+a lenient one readily. The gate above is the baseline those precepts modulate — the floor beneath the
+flavour, so the decision is coherent whether or not Ideology is installed.
+
+---
+
+## How to play with parole
+
+- **Parole is earned, not granted.** You cannot release your way out of a deep record. Decide early
+  whether a pawn is a keep-or-release case and treat (gently) the ones you mean to free.
+- **Reform 0.30 is three gentle acts, minimum.** Nothing faster reaches it. Start early.
+- **Keep the record shallow if you want the option.** Every escape (+0.35) and catch (+0.15) you let
+  accumulate pushes a pawn toward the unparoleable side of the 1.2 line.
+- **A parolee who stays is a Corrections case, not a farewell.** They carry their record; if conditions
+  sour, their disposition (still reading their history) can put them back on it.
+
+---
+
+*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs · Ward.*

corrections/Regime.md

@@ -0,0 +1,89 @@
+# Regime
+
+*The daily life of the held — and the one lever vanilla withholds.*
+
+Most of what a prison regime needs, vanilla already gives you. The schedule is the Restrict tab. The
+mood-driven disposition already flows through the colony's underlying systems — a neglected prisoner
+runs hotter with no new machinery. So Regime does not rebuild any of that. It adds the single thing
+vanilla flatly refuses to model: **recreation.**
+
+---
+
+## What vanilla does, and what Regime flips
+
+Vanilla denies prisoners the **Joy** (recreation) need outright — the need is flagged colonists-only, so
+it simply never appears on a prisoner. A caged pawn has no recreation bar, cannot take joy from
+anything, and never suffers for its absence.
+
+Regime flips exactly that one bit on — the same approach the good, popular **Prisoner Recreation** mod
+takes. It grants the recreation need to **humanlike prisoners of your colony** and nothing else: animals,
+guests, slaves and colonists are untouched, only the recreation need is affected, and it only ever
+*adds* the need where vanilla withheld it — it never removes a need another mod granted.
+
+That is the entire mechanism. Enabling recreation is trivial — once the need exists, vanilla does all
+the rest (joy sources, the recreation bar, the mood effects of a full or empty one). The *value* is not
+the plumbing; it is what an empty bar now costs.
+
+---
+
+## Why a need you can neglect is the point
+
+Giving prisoners recreation is not a mercy toggle — it is a **lever with two ends**, and the down end is
+the one that matters to the suite. Once a prisoner *has* the Joy need, they can be **starved** of it, and
+vanilla's own machinery then does the work: no recreation lowers Joy, which lowers mood, and a low mood
+raises the pawn's disposition — their odds on every "would they?" roll.
+
+Every one of those steps already exists. Regime only opens the first door; mood is wired to disposition
+in Core, so a prisoner who gets no yard time stews, their mood sinks, and their disposition climbs.
+From [Deterrence](Deterrence.md) and [Discipline & Reform](Discipline-and-Reform.md) you already know
+disposition is the multiplier the whole system keys off; Regime is what lets *neglect* feed it.
+
+Concretely, a prisoner's mood pushes their disposition into these brackets:
+
+| Prisoner condition | Disposition contribution |
+|---|---|
+| Mood below 0.20 (recreation-starved, at the floor of despair) | ×2.5 |
+| Mood below 0.35 (badly kept) | ×1.6 |
+| Held **and** mood below 0.40 (a badly run cell) | an additional ×1.4 |
+
+A prisoner you give no recreation is a prisoner you are pushing up those brackets. Regime turns "I
+didn't bother building a rec room" from a non-event into a disposition cost you pay on every roll.
+
+---
+
+## Works alongside Prisoner Recreation
+
+If you also run the **Prisoner Recreation** mod, nothing breaks. Both mods do the same thing — grant the
+recreation need to prisoners — and because Regime only acts when the need isn't already granted,
+whichever runs first grants it and the other sees it already done. Running both is harmless. Running
+either alone is sufficient. There is no double-need, no conflict, no load-order sensitivity between them.
+
+Regime prints a short startup message so you can confirm it loaded and prisoner recreation is enabled.
+
+---
+
+## Content on top
+
+Yard time, safety needs, and visitation are *content* on this foundation, not new machinery. Each of
+them is just another thing that moves a prisoner's mood — and mood is already wired to disposition — so
+they build on the same spine that this one recreation change put in place. When they land, they make a
+well-run regime feel richer without adding new systems underneath.
+
+---
+
+## How to play with Regime
+
+- **Build the rec room.** A prisoner with recreation settles; the mood brackets above stay off, and
+  their disposition sits near baseline. A cheap horseshoe pin or chess table earns its keep in crimes
+  that don't happen.
+- **Neglect is a choice with a number.** Leaving prisoners with nothing to do isn't neutral — it drives
+  mood into the ×1.6 and ×2.5 disposition brackets, and a hotter prisoner reoffends, which cools your
+  colony's climate of order, which heats *everyone*. The rec room is deterrence you build once.
+- **Recreation and reform stack.** Regime cools disposition *live* (through mood); reform cools it
+  *permanently* (through [Discipline & Reform](Discipline-and-Reform.md)). A reformed prisoner in a
+  well-run wing is calm on both axes — which is exactly the pawn you can eventually [parole](Parole.md).
+- **You don't need Prisoner Recreation too** — but if you have it, keep it. They coexist.
+
+---
+
+*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs · Ward.*

corrections/Rehabilitation.md

@@ -0,0 +1,151 @@
+# Rehabilitation
+
+*The warden work that drives discipline, reform, and parole.*
+
+Classification, discipline, deterrence, and parole set the rules — a grade over the record, a reform
+score punishment moves, an order climate, a release decision. Rehabilitation is what a warden actually
+*does* day to day to move a prisoner through them. Without it, reform sits still, classification never
+re-grades, and parole never fires; with it, the whole post-arrest arc comes alive.
+
+It gives corrections the same shape Ward gives psychiatric care — a **prisoner interaction mode**,
+**warden work**, an **alert**, and an **inspect readout** — so a warden reforms a prisoner over time and
+paroles them when they have turned a corner.
+
+---
+
+## The two modes
+
+Both are non-exclusive prisoner interaction modes (the same kind Prison Labor and Ward use), so they
+stack with each other and with recruit / reduce-resistance.
+
+| Mode | What a warden does | Result |
+|---|---|---|
+| **Rehabilitate** | Runs counselling sessions on the prisoner | Reform rises, the reform bar fills, colony order rises |
+| **Parole when reformed** | Releases the prisoner **once they are eligible** | A paroled colonist, back in the colony |
+
+Set **Rehabilitate** alone to run the programme and parole by hand when the alert fires; set **both**
+for a hands-off "reform, then release" pipeline. A prisoner flagged for parole who is *not yet* eligible
+is simply not acted on — the warden waits.
+
+---
+
+## A rehabilitation session
+
+A warden walks to the prisoner and counsels them for about 20 in-game minutes, with Social as the
+active skill. On completion (never on interruption — you only earn credit for a finished session), one
+session does three things:
+
+1. **Corrective discipline** — a gentle disciplinary act: reform **+0.10**, and it raises the colony's
+   **order** by **+0.12**. This is the deterrence-up half that punishment alone never triggered —
+   visible corrective justice deters everyone else.
+2. **The reform bar** — the visible progress bar fills, by **0.34 × cell quality × skill** per session,
+   and it **decays −0.08/day**, so rehabilitation has to be *sustained*.
+3. **A memory** — the prisoner feels counselled (a small mood lift).
+
+| Input | Range | Depends on |
+|---|---|---|
+| skill factor | 0.5 … 1.0 | the warden's Social level |
+| cell quality | 0.5 … 1.5 | the cell's impressiveness |
+| reform per session | +0.10 | fixed |
+| order per session | +0.12 | fixed |
+
+Reform reaches the parole bar (0.30) in roughly **three completed sessions** — faster than a bad cell or
+a poor counsellor fills the visible bar. So the "Ready for parole" alert keys off the real gate, not the
+bar you see filling.
+
+---
+
+## Neglect — the teeth
+
+A prisoner you flag for rehabilitation and then never attend **hardens**, exactly as a ward you don't
+staff does. Once more than **two days** pass since the last real session, reform falls **−0.15/day** and
+they resent it (a mood hit). This hardening lowers reform *directly*, not as an act of visible justice —
+neglect is passive prisonization, so unlike a session it does **not** raise the colony's order.
+
+Attend the prisoner and the clock resets; flag them and walk away and they slide back toward the record
+that put them in. "A reform programme you don't staff is worse than none."
+
+---
+
+## Parole — the release that stays
+
+When a rehabilitated prisoner clears the parole gate — reform 0.30 or higher, security grade Medium or
+below, not already pardoned — the **Ready for parole** alert names them. A warden set to Parole then
+processes the release:
+
+- marks the **pardon** on the record;
+- clears the prisoner hold so a former prisoner becomes a **free colonist again** — a parolee who
+  *stays* in the colony carrying their record, not vanilla's release that ejects them from the map;
+- a grateful memory, and a small **+0.03** to order (a lawful release is visible justice too).
+
+The parolee keeps their record, so if they reoffend the [policing](Policing.md) loop catches them again
+— recidivism, closing back onto the start.
+
+---
+
+## Discipline — the other lever
+
+Rehabilitation is the carrot; **discipline** is the stick, and its opposite. Set a prisoner to
+**Discipline** and a warden puts them in **solitary**: harsh discipline *hardens* them — reform falls —
+yet raises the colony's order (visible harsh justice deters the rest), and it stings: a mood hit and an
+on-edge *in solitary* status. It fires at most once per term (the status blocks re-discipline for about
+two days), so it holds order without cratering reform in a single day. The tension is the point: lean on
+discipline to keep order and you make the punished harder to reform.
+
+## Classification enforcement
+
+Classification always computed a **security grade** (Minimum..Supermax); now it is actionable:
+
+- **The grade shows** on every prisoner's inspect pane — the game tells you who is dangerous instead of
+  leaving you to guess.
+- **Wing-routing.** A wall-mounted **security marker** grades the cell block it stands in
+  (Minimum..Supermax, set with a gizmo). One marker covers a *whole block* — a prisoner takes the grade
+  of the nearest marker in range, so you tag a corridor once rather than cluttering every cell. A
+  **"Dangerous prisoner unsecured" alert** then flags any prisoner held in a wing too weak for their
+  grade, and the inspect pane shows their wing and a **MISPLACED** warning — move them to a stronger
+  wing. An ungraded wing falls back to flagging an unsegregated Maximum/Supermax pawn.
+- **Cell safety:** a prisoner caged with a dangerous one suffers a mood penalty. Segregate your
+  dangerous prisoners, or their cellmates pay for it — the grade made to matter on the *housing* side,
+  not only at parole.
+
+## Regime — yard, lockup, and visitors
+
+Beyond punishment and reform, the held have a **daily life**:
+
+- **Yard / Lockup schedule.** Two timetable blocks set a held pawn's day: **Yard** allows recreation
+  (with the prisoner recreation need Regime enables, they head out to a rec area), **Lockup** confines
+  them to the cell and stews their mood. The timetable itself is **Prison Labor's** — Corrections reads
+  it when PL is present and does nothing without it, so PL stays compatible.
+- **Visitors.** A prisoner or ward patient with family or a bond gets **visitors** — a friendly party
+  walks in under the game's own visitor AI and congregates by their cell, and the break from isolation
+  lifts their mood. Thematically strongest for a ward patient whose family comes to see them.
+
+---
+
+## Seeing it
+
+Every colony prisoner's inspect pane now carries the corrections readout:
+
+> *Security grade: Maximum* · *In solitary* · *Rehabilitation: reforming (40%) — neglected (3d)* ·
+> *reformed — ready for parole*
+
+The **grade** shows for every held pawn; *in solitary* while a discipline term runs; the
+**rehabilitation** line for a pawn set to reform. And because the colony's **order climate** otherwise
+has no readout at all, the same pane surfaces it when it is far enough from ordinary to matter —
+*Colony order: low (28%) — crime pays here* / *high (71%) — order holds*.
+
+---
+
+## What this closes
+
+With rehabilitation in play, the whole post-arrest arc runs: **discipline** moves reform,
+**classification** re-grades as reform rises, **deterrence** climbs on visible justice (not just falls
+on crime), **parole** releases the reformed, and Core's **treatment** carries the reform bar the same
+way it carries Ward's recovery. The loop closes back onto disposition — catching, reforming, and
+releasing one pawn moves the climate every other pawn is judged against.
+
+The whole corrections layer can be toggled off in the mod's settings, like the rest of the suite.
+
+---
+
+*Part of the **Institution** suite.*

gangs/Affiliations-and-Segregation.md

@@ -0,0 +1,91 @@
+# Affiliations and segregation
+
+*Gangs grow out of who pawns **already are** — and the counter-play is to keep the wrong pawns apart.*
+
+A gang in this mod is never invented from nowhere. It crystallises along the bonds a colony already
+contains: shared faction, shared faith, or real friendship. This page covers the formation rule — which
+bonds count and why the *same room* requirement matters — and then the segregation counter-play that
+turns those same bonds against the network.
+
+## The formation rule
+
+On each 5000-tick pass, the game walks everyone currently over the join bar (Nature × Nurture ≥ 0.9)
+and tries to pair each unaffiliated pawn with a mate. A pawn pairs up with someone who is, at that
+moment, **in the same room** *and* someone they **already share a bond with**.
+
+Two conditions, both required: they must be **in the same room** at the moment of the check, **and**
+they must **share an affiliation**. A disposed pawn does not fall in with a stranger across the map; it
+falls in with someone it is standing next to *and* already connected to.
+
+Pairing binds them together: if either already runs with a gang, the other joins that gang; otherwise a
+fresh gang is founded. So gangs accrete — a new member pairing with an existing member is absorbed
+into the existing crew rather than starting a rival one.
+
+### What counts as an affiliation
+
+| Bond | Condition | Notes |
+|---|---|---|
+| **Same faction** | both belong to the same (non-empty) faction | your colonists share one; captured raiders share theirs |
+| **Same ideoligion** | both follow the same ideoligion, only if the Ideology DLC is active | needs Ideology enabled |
+| **Friendship** | an opinion of at least **+20** of each other | a real positive relationship, not mere acquaintance |
+
+The design intent:
+
+> Gangs grow out of who pawns ALREADY are, not out of nowhere — so a prisoner's gang on the outside is
+> their old faction/friends, and rival factions run as rival gangs.
+
+This is why the system feels coherent rather than arbitrary. A crew is a faction bloc, a congregation,
+or a friend group — social lines the colony *already has*. Gangs mesh with them instead of stamping
+random groupings over the top.
+
+## Rival factions become rival gangs
+
+Follow the rule to its conclusion. Two captured raiders from **different** hostile factions each share
+an affiliation with *their own* side but not with each other. Housed in the same wing, each pairs up
+along its own faction line — and now you have **two gangs**. As the
+[Rivalry and Fights](Rivalry-and-Fights.md) page explains, members of two different gangs are
+automatically **rivals**, and rival-gang violence between them is booked as a crime.
+
+So the affiliation rule and the rivalry rule are two ends of one idea: **who bands together** and **who
+is opposed** both derive from pre-existing loyalties. Mix hostile factions or clashing ideoligions in
+one room and you have not made one big gang — you have made two rival ones and lit the fuse between
+them. This is a housing decision with mechanical teeth.
+
+## Segregation: the counter-play
+
+Here is where the formation rule and the network rule meet, and where the rest of the suite earns its
+keep. A gang can only *do* anything — resupply itself — if its members can **reach** each other.
+Passing contraband requires two things: the pawns must be in the same gang, **and** two pawns both on
+the map must have a walkable path between them. Break the path and you break the network.
+
+The design calls this out as the intended answer to the whole mod:
+
+> The counter-play is the rest of the suite: Classification SEGREGATES rivals into different wings, and
+> a network whose members cannot REACH each other is starved.
+
+**Classification** lives in **Institution: Justice**. It grades pawns by risk and lets you sort them
+into separate, walled wings. Two gangmates graded into different wings, with no walkable route between
+them, fail the reach test on every network pass. The gang still *exists* — they are still the same crew,
+still rivals of the other crew — but it can no longer pass a shiv from a holder to a have-not. **A
+network that cannot reach itself is a network that cannot supply itself.**
+
+This is the elegant part of the design: the very bonds that formed the gang tell you *who to keep
+apart*, and the reach requirement makes keeping them apart actually starve the supply chain. You do not
+disband a gang; you **cut it off from itself** until nothing can move along it.
+
+## How to play it
+
+- **Read affiliations before you house pawns.** Same-faction and same-ideoligion prisoners will band
+  together; hostile factions in one wing will form *rival* gangs and fight. Sort deliberately.
+- **Segregate by Classification, not by hope.** Putting rivals in "different areas" is not enough —
+  resupply only needs a *walkable path* between two gangmates. A shared corridor is a supply line. Use
+  genuinely separate, walled wings.
+- **Starve, don't chase.** You will rarely delete a gang outright. The durable win is to keep its
+  members unable to reach one another so the network dries up, while keeping mood and deterrence high so
+  few pawns cross the join bar in the first place (see [Joining](Joining.md)).
+- **Watch the outside valve.** Segregation starves *internal* resupply; a bent warden can still inject
+  new contraband from outside (see [Networks and Smuggling](Networks-and-Smuggling.md)). Partition the
+  wing *and* clean up your wardens for a network that genuinely goes dark.
+
+---
+*Part of the **Institution** suite — Core · Contraband · Justice · Gangs (this). Each mod stands alone; together they are one system.*

gangs/Home.md

@@ -0,0 +1,88 @@
+# Institution: Gangs
+
+*Gangs as **contraband economies** — not mood. The social capstone of the **Institution** suite of
+RimWorld 1.6 mods.*
+
+---
+
+## What Gangs is
+
+Gangs turns the loose, disposed pawns in your colony — colonists, prisoners, slaves — into a
+**network** that moves contraband. When disposition and circumstance line up, pawns who already share
+a bond band together, and a member who holds a stash quietly resupplies a member who has none. A
+search that turns up nothing on one prisoner has therefore *not* cleaned out the wing: the wing is a
+supply chain, and you only searched one link.
+
+That is the entire point, and it is a deliberately narrow one. Gangs does not do mood. It does not do
+a "gang leader buff." It does the one thing nothing else in the ecosystem does — it makes contraband
+**flow between pawns**, and then hands you the tools to cut the flow.
+
+## The gap it fills (and the one it doesn't)
+
+If you run **Prisoner Realism**, its *Ringleader* system already models a dominant prisoner spreading
+unrest and mood contagion through a wing. That system is good, and Gangs does not touch it. Ringleader
+owns *influence and mood*.
+
+Gangs owns the thing Ringleader has no equivalent for: **the network as a supply chain.** Contraband
+physically changes hands along social lines. A stash on one pawn is a stash available to the whole
+gang. The two systems are complementary — run both. Ringleader tells you *who stirs the pot*; Gangs
+tells you *how the shivs get around*.
+
+## Why it needs the whole suite
+
+Gangs is the module built **last**, because it needs every other Institution mod already in place. It
+is not a standalone feature; it is the suite working together, and it is honest about that in its
+dependencies:
+
+| It asks... | ...and the answer comes from |
+|---|---|
+| *Who is disposed enough to join?* | **Institution: Core** — the propensity engine that scores each pawn's Nature and Nurture |
+| *What do they move?* | **Institution: Contraband** — concealment, stashes, search, and the bent-warden supply route |
+| *Where does a fight get booked, and how are rivals kept apart?* | **Institution: Justice** — the crime/deterrence loop, and Classification's segregation |
+
+Remove any one of those and Gangs has nothing to stand on. It is the place where Core's spectrum,
+Contraband's stashes, and Justice's policing all cash out at once.
+
+## A healthy colony grows few gangs — or none
+
+This is the thesis, and it is enforced in the numbers, not just the flavour. Membership is gated at a
+Nature × Nurture score of **0.9 or higher** — a high bar on purpose. A disposed pawn who is
+**well-kept and well-policed** does not band up: their nurture multiplier stays low, and deterrence
+pulls it lower still. It takes a foul streak (nature) *and* a badly-run situation (nurture) at the
+same time.
+
+So a gang problem is a **symptom**. It is the game telling you that a wing is mistreated, under-policed,
+or both. The fix is never "fight the gang system" — it is to run a better prison. Feed them, give them
+recreation, keep deterrence high, segregate rivals, and the networks starve on their own.
+
+> A gang is a symptom of a badly-run colony, not furniture.
+
+## The pages
+
+- **[Joining](Joining.md)** — why the join bar (Nature × Nurture ≥ 0.9) is high, why good treatment and
+  deterrence keep pawns *out*, and how membership is re-checked for every kind of pawn.
+- **[Networks and Smuggling](Networks-and-Smuggling.md)** — how a holder resupplies a needy gangmate,
+  the *same-gang-and-can-reach* rule, why this defeats a single search, and how a bent warden refills a
+  starved network from outside.
+- **[Rivalry and Fights](Rivalry-and-Fights.md)** — how a gang fight is booked as a crime through
+  Justice, why inside-the-wire and out-on-the-street are the same offence, and how it feeds deterrence.
+- **[Affiliations and Segregation](Affiliations-and-Segregation.md)** — shared faction, faith, or
+  friendship plus *same room* as the formation rule, why rival factions become rival gangs, and how
+  Classification's segregation is the counter-play that starves a network which cannot reach itself.
+
+## The suite
+
+Part of the **Institution** suite of RimWorld 1.6 mods:
+
+- **Institution: Core** — the propensity engine (Nature × Nurture), criminal records, secured context.
+- **Institution: Contraband** — concealment, improvised shivs, tunnels, warden search and corruption.
+- **Institution: Justice** — Classification, Deterrence, Discipline, Parole, Regime.
+- **Institution: Gangs** — this mod: joining, networks/smuggling, rivalry/fights.
+
+Sibling projects: **Foul Play** (the vessel/substance framework and the "Piss Nuke") and **Ward** (a
+ward/treatment prison mode).
+
+Each mod stands alone as an install; together they form one system.
+
+---
+*Part of the **Institution** suite — Core · Contraband · Justice · Gangs (this). Each mod stands alone; together they are one system.*

gangs/Joining.md

@@ -0,0 +1,113 @@
+# Joining a gang
+
+*How Gangs decides who runs with a crew — and why a well-run colony keeps almost everyone out.*
+
+Membership is not random, and it is not a mood event. A pawn joins a gang only when their **disposition
+and their circumstances line up at once** — the same Nature × Nurture propensity that drives every
+other behaviour in the Institution suite. This page covers the exact test, why the bar is set where it
+is, and how you keep pawns on the right side of it.
+
+## The rule
+
+A pawn joins when their **Nature multiplied by their Nurture reaches 0.9 or higher**. Only humanlike
+pawns are ever eligible — animals and mechs never join.
+
+Beyond that it is one line of arithmetic: multiply the pawn's **Nature** by their **Nurture** and
+compare to **0.9**. There is no dice roll here. The same pawn in the same situation always gives the
+same answer — join, or don't. (That makes membership different from one-off acts like a piss spree,
+which *do* roll the dice each time. Gang membership is a standing condition, so it uses the raw product
+with no randomness.)
+
+### The two halves
+
+Both terms come from **Institution: Core** — see Core's own documentation for the full tables — but you
+need the shape of them to understand the bar:
+
+- **Nature** (`0` to `1`) is *who the pawn is*: a base of `0.05`, plus trait weights, floored at `0`
+  and capped at `1`. Psychopath `+0.45`, Bloodlust `+0.35`, Kleptomaniac `+0.40`, Greedy `+0.25`,
+  Abrasive `+0.15`; and it goes **down** for Kind `−0.30` or Ascetic `−0.15`. This is fixed at pawn
+  creation and barely moves.
+- **Nurture** (a multiplier, roughly `0.4` at the floor, `1.0` at baseline) is *the situation you put
+  them in*: a floored mood multiplies it up hard (roughly `×2.5` under 0.20 mood, `×1.6` under 0.35),
+  being held while miserable adds more (`×1.4`), a hardened record (negative reform) raises it, and —
+  critically — **deterrence pulls it down** (toward about `0.7` in a high-deterrence colony; a neutral,
+  baseline order sits at `1.0`). This is the half you control.
+
+## Why the bar is high
+
+`0.9` is a deliberately steep threshold. In the design's own words:
+
+> A high bar, on purpose: gangs are a symptom of a badly-run colony, not furniture. A healthy Rimworld
+> — content pawns, an orderly colony — grows few gangs, if any.
+
+Because the two terms are **multiplied**, both have to be substantial for the product to clear `0.9`.
+A nasty pawn in a happy, policed colony has a low nurture and stays out. A saintly pawn in a hellhole
+has a near-zero nature and stays out. You only get a gang when a genuinely disposed pawn is *also*
+neglected or unpoliced — foul streak **and** bad situation, together.
+
+That is the design speaking through the arithmetic: a gang is never bad luck. It is feedback.
+
+## Worked examples
+
+All numbers below use Core's documented factors; the intermediate nurture figures are rounded to show
+the shape of the decision.
+
+| Pawn | Nature | Situation → Nurture | Product | Joins? |
+|---|---|---|---|---|
+| **Kind colonist**, ordinary life | `0.05 − 0.30`, floored at `0.00` | content, `≈ 1.0` | `0.00` | **No** — nature floors it |
+| **Greedy prisoner**, content, policed | `0.30` | fed & high deterrence, `≈ 0.7` | `≈ 0.21` | **No** |
+| **Greedy prisoner**, starved & neglected | `0.30` | mood floored + held, `≈ 3.5` | `≈ 1.05` | **Yes** |
+| ...same pawn, but you raise deterrence | `0.30` | `× ≈ 0.7` → `≈ 2.45` | `≈ 0.74` | **No** — deterrence tipped them out |
+| **Psychopath + Bloodlust**, mood floored | `≈ 0.85` | mood floored + held, `≈ 3.5` | `≈ 2.9` | **Yes** — nothing short of reform pulls this back |
+
+The middle rows are the whole game of it. The **same greedy prisoner** joins or abstains purely on how
+you run the wing. The Kind colonist and the near-maxed psychopath are the fixed poles: one essentially
+cannot join, the other essentially always will if you neglect them. Everyone in between is a policy
+choice.
+
+## It works for every pawn, everywhere
+
+There is no "prisoners only" special case: any pawn — colonist, prisoner, slave — can run with a crew,
+wherever they are.
+
+Membership pays no attention to a pawn's secured status. A disposed **free colonist** can run with a
+crew on the outside; a **prisoner** can run with theirs on the inside; a **slave** likewise. This is
+what lets a gang span the wall — an outside member and an inside member of the same crew (see
+[Networks and Smuggling](Networks-and-Smuggling.md)). Being held raises nurture (misery), but it is not
+a requirement.
+
+## The cadence: every 5000 ticks
+
+Gang membership is re-evaluated on a fixed interval — every **5000 ticks**, which is about **2 in-game
+hours** (a RimWorld day is 60,000 ticks), or roughly **80 seconds** of real time at normal (1×) speed.
+On each pass, the game:
+
+1. Gathers everyone on the map who currently meets the Nature × Nurture ≥ 0.9 join bar.
+2. Pairs up unaffiliated members who **share a room and a bond** into gangs (see
+   [Affiliations and Segregation](Affiliations-and-Segregation.md)).
+3. Runs one round of network resupply inside each gang (see
+   [Networks and Smuggling](Networks-and-Smuggling.md)).
+
+Because the join bar is re-checked from scratch every pass, membership is *live*: a pawn whose situation
+improves until the product drops back under `0.9` simply stops being eligible to form new bonds. The
+bar is not a one-time gate at recruitment — it is a standing condition the colony is continuously graded
+against.
+
+## How to keep pawns out
+
+You do not fight the gang system. You lower nurture, which lowers the product, which drops pawns below
+`0.9`:
+
+- **Feed them and give them recreation.** Mood is the biggest nurture multiplier by far. A wing above
+  0.35 mood loses the `×2.5`/`×1.6` spikes entirely.
+- **Keep deterrence high** (Institution: Justice). Deterrence scales nurture down toward `0.7`; a
+  well-policed colony is *arithmetically* less gang-prone. This is the row in the table above where the
+  same greedy prisoner flips from *joins* to *abstains*.
+- **Reform, don't just punish.** A hardened record (negative reform) *raises* nurture; discipline that
+  actually reforms (positive reform) lowers it. Harsh punishment that prisonizes a pawn makes the
+  gang problem worse, not better.
+- **Accept the two poles.** A near-maxed psychopath will run with someone the moment you slip; a Kind
+  pawn essentially never will. Spend your attention on the middle.
+
+---
+*Part of the **Institution** suite — Core · Contraband · Justice · Gangs (this). Each mod stands alone; together they are one system.*

gangs/Networks-and-Smuggling.md

@@ -0,0 +1,105 @@
+# Networks and smuggling
+
+*The one thing nothing else models: contraband that flows **between** pawns. A gang is a supply chain.*
+
+This is the core of the mod. Everything else — who joins, who fights, who is kept apart — exists to
+serve or to break the network described here. A gang is not a mood aura; it is a **supply chain**, and
+contraband flows along it.
+
+## The move
+
+The heart of it is a single transfer: a gangmate who is holding a stash passes one piece of it to a
+gangmate who has none. Here is everything that has to be true for a piece to move:
+
+- both pawns are in the **same gang**;
+- if both are on the map, the supplier has a **walkable path** to the customer (touch range, willing to
+  cross deadly danger to get there);
+- there is contraband in play on the map at all;
+- the supplier is actually holding at least one concealed item.
+
+When all of that holds, the supplier's first concealed item leaves their hands and arrives — still
+hidden — on the customer.
+
+A few things worth reading carefully:
+
+- **One item per move.** It moves the first concealed item on the supplier, and exactly that. It is a
+  redistribution, not a duplication: the item leaves the supplier and arrives concealed on the customer.
+  The gang's total stash is unchanged; only *who holds it* changes.
+- **Same gang, always.** Both pawns must belong to the same gang. There is no smuggling to a stranger —
+  the network only moves along membership.
+- **The reach requirement only applies to pawns both on the map.** Two pawns physically present must
+  have a walkable path between them. If a member is off the active map, the reach check is skipped —
+  which is what allows a gang to reach across the wall to a member who is not on the map right now.
+
+## Why this defeats a single search
+
+Consider a wing of four gangmates and one shiv. You search Prisoner A and find nothing — clean. You
+tick a box: *cell searched, no contraband.* But the shiv was on Prisoner C the whole time, and on the
+next 5000-tick network pass it will move to whoever is out. Search C tomorrow and it may already be on
+A again.
+
+Put plainly:
+
+> A gangmate holding a stash supplies one who has none, so a search that turns up nothing on one
+> prisoner has not cleaned out the wing.
+
+A single search is a snapshot of one pawn in a network that reshuffles itself. This is the whole reason
+contraband-as-a-network is worth modelling: **the unit of contraband is the wing, not the pawn.** To
+clean it out you have to either search faster than it moves, or — far better — break the network.
+
+## The automatic resupply pass
+
+You never trigger a transfer by hand; the game runs it automatically on the 5000-tick pass. After
+forming gangs for the pass, it runs one resupply round **per gang**: it finds the first member who *is*
+hiding contraband and the first member who is *not*, and if both exist, moves one item from the holder
+to the empty-handed member.
+
+So on each interval, every gang that has both a haves-member and a have-not-member performs **one**
+transfer, moving a single item from a holder to someone empty-handed. Over several passes the effect is
+that a gang tends to keep its members supplied and to spread a stash out — which is exactly what makes
+a scattershot search miss it. (Only members who currently meet the join bar take part in this automatic
+pass.)
+
+## The cross-wall move
+
+Because neither the join bar nor gang membership cares about a pawn's secured status, a gang can have a
+**free** member and a **held** member. If the free member is holding the stash, the network resupplies
+*into* the prison — the outside man passes to the inside man. A free colonist and a prisoner can be in
+one gang with the stash on the free member; the transfer succeeds, and afterwards the prisoner is hiding
+contraband and the colonist is not. Your prison's contraband problem is not sealed inside your prison.
+
+## Resupply from outside: the bent warden
+
+The transfer only *redistributes* what a gang already has. So what happens when you finally search the
+whole wing on the same day and strip every member clean — there is nothing left to pass around? The
+gang is starved. It stays starved until contraband **re-enters** from outside.
+
+That external source is not part of Gangs; it is **Institution: Contraband's** corruption route. A
+warden's honesty varies by personality (a Greedy warden has a price), and a bent warden can *smuggle
+contraband in to a prisoner*, planting a concealed item directly. That single planted item is then all
+the network needs: one holder, and the next 5000-tick pass spreads it back out across everyone who can
+reach.
+
+So the two halves of the supply picture are:
+
+| Mechanism | Owner | What it does |
+|---|---|---|
+| Passing contraband between gangmates | **Gangs** | moves existing contraband *between* gangmates who can reach each other |
+| Warden smuggling | **Contraband** | injects *new* contraband from outside via a corruptible warden |
+
+Cut both and a gang genuinely dries up. Cut only the redistribution and a bent warden re-seeds it; cut
+only the warden and any stash you missed keeps circulating.
+
+## How to break a network
+
+- **Search the whole wing at once**, not one pawn at a time. A partial sweep is a snapshot the network
+  routes around.
+- **Segregate rivals into different, unreachable wings** (Classification, in Institution: Justice). The
+  reach requirement is the lever — a network whose members cannot walk to each other cannot pass
+  anything. This is the primary counter-play; see
+  [Affiliations and Segregation](Affiliations-and-Segregation.md).
+- **Clean up your wardens.** If searches never seem to finish the job, you may have a Greedy warden
+  re-seeding the wing. Corruption is the resupply valve; personality is the fix.
+
+---
+*Part of the **Institution** suite — Core · Contraband · Justice · Gangs (this). Each mod stands alone; together they are one system.*

gangs/Rivalry-and-Fights.md

@@ -0,0 +1,98 @@
+# Rivalry and fights
+
+*Two gangs, one grudge. A gang fight is a **crime** — booked, attributed, and fed back into the colony's
+climate of order.*
+
+Gangs do not just supply themselves; they collide. Where the network is about who shares, rivalry is
+about who is opposed — and, crucially, about turning gang violence into something the rest of the
+suite can *see* and *police*.
+
+## Who is a rival
+
+The rule is exactly as blunt as it sounds: **two pawns in two different gangs are rivals.** Both must
+actually be in a gang, and it must be a *different* gang for each. As the design puts it:
+
+> Two pawns of DIFFERENT gangs are rivals — inside the wire or out on the street.
+
+Note what is *not* required. There is no separate "hostility" flag, no rival-declaration event, no
+threshold to cross. The moment two crews exist, their members are rivals of one another. Rivalry is a
+structural fact about who is in which gang, not a mood or a relationship value.
+
+Two consequences fall straight out of that:
+
+- **Non-members are nobody's rival.** A pawn in no gang — everyone in a healthy colony — is never a
+  rival to anyone, because rivalry needs *both* pawns to be in a gang. No gangs, no rivalry.
+- **Same gang, never rivals.** Members of one crew are in the *same* gang, so they are not rivals.
+  Within a gang there is no rivalry to book; there is the network (see
+  [Networks and Smuggling](Networks-and-Smuggling.md)).
+
+Where do two *different* gangs come from in the first place? From the affiliations pawns already have —
+rival factions and rival ideoligions form into separate crews. That is the subject of
+[Affiliations and Segregation](Affiliations-and-Segregation.md); the short version is that gangs mesh
+with the colony's existing social fault lines, so **rival factions run as rival gangs.**
+
+## A fight is a crime
+
+The payoff of tracking rivalry is what happens when rivals fight. When a rival-gang attack happens, it
+is not treated as generic brawling — it is booked as a crime through the same Justice pipeline as any
+other offence.
+
+Only rival-gang violence counts: the two pawns must be in different gangs for anything to be recorded.
+A scuffle between gangmates, or between two non-members, is not a *gang* fight and is not booked. When
+it *is* rival-gang violence, the whole event is recorded as a crime against the **attacker**, and that
+does three things at once (they live in Institution: Justice, but this is what Gangs is leaning on):
+
+| Effect of booking a gang fight | Where it lands |
+|---|---|
+| the attacker's crime count goes up | their criminal record (Core) |
+| the time of the crime is stamped to now | their criminal record (Core) |
+| the colony's **deterrence** nudges **down** (a crime happened; order slipped) | Justice's deterrence system |
+
+## Inside the wire and out on the street are the same offence
+
+This is the design point the mod is emphatic about:
+
+> A gang fight is a CRIME — it goes on the attacker's record and moves the colony's climate through
+> the same Justice loop as any other, so it can be investigated, attributed and policed. Rival-gang
+> violence inside a prison and out on the street are the same offence.
+
+There is no separate rule for a prison-yard shanking versus a colonists' brawl in the dining room. A
+fight is booked purely on whether the two pawns are rivals. A free colonist who is a gang member
+attacking a rival is booked identically to a prisoner doing the same in a cell block. The gang system
+does not care which side of the wall the violence is on — only that it was between rivals.
+
+This is what makes gang violence *legible* to the rest of the suite. A fight is not a one-off flavour
+event that scrolls past in the log; it is a record entry with an attributed perpetrator and a timestamp,
+which means it can be investigated, blamed on a specific pawn, and answered.
+
+## How it feeds deterrence — and back into joining
+
+Here is the loop that closes the whole suite:
+
+1. A rival-gang fight is booked as a crime against the attacker.
+2. That nudges the colony's **deterrence down**. Order has visibly slipped.
+3. Lower deterrence *raises* the nurture multiplier for **every** disposed pawn on the map (less
+   deterrence means a bigger multiplier).
+4. Higher nurture pushes more pawns over the Nature × Nurture ≥ 0.9 join bar (see
+   [Joining](Joining.md)).
+5. More members → more rivals → more fights available to be booked.
+
+Left unanswered, gang violence is self-reinforcing: each booked fight makes the next one likelier. The
+brake is the other half of Justice — **punishment raises deterrence back up**, which lowers nurture,
+which drops borderline pawns back under the bar. The seesaw works both ways: punishing a pawn raises the
+deterrence level, and a fresh crime lowers it again.
+
+## How to play it
+
+- **Respond to booked fights.** A gang fight is real feedback that deterrence has slipped. Punishing the
+  attributed attacker is not just retribution — it is the mechanical lever that pulls deterrence back
+  up and cools the whole map's propensity.
+- **Don't manufacture two gangs where there was one.** Rivalry needs two different crews. Housing pawns
+  of hostile factions or clashing ideoligions together is what creates the second gang and the fights
+  between them — see the next page.
+- **Read the record, not the moment.** Because every fight is attributed to a perpetrator, a thick
+  record of gang violence points you at *who* to segregate, discipline, or parole — the same tools the
+  rest of the suite already gives you.
+
+---
+*Part of the **Institution** suite — Core · Contraband · Justice · Gangs (this). Each mod stands alone; together they are one system.*

policing/Deterrence.md

@@ -0,0 +1,130 @@
+# Deterrence — the feedback loop
+
+*The connection that turns the pipeline into a cycle.*
+
+This is the part that makes policing **govern** rather than merely clean up. Everything else in Justice
+reacts to one pawn: this reacts to the *whole colony*, and it feeds **back** into every pawn's
+disposition. Crime that goes unanswered emboldens everyone a little; visible justice deters everyone a
+little. The reason to punish is not just this prisoner — it is the message it sends the rest, and here
+that message is a number they all read.
+
+---
+
+## The climate of order
+
+Every colony carries one order value:
+
+| | |
+|---|---|
+| **Range** | 0.0 (lawless) … 1.0 (iron) |
+| **Baseline** | 0.5 — an ordinary colony |
+| **Below baseline** | crime pays; dispositions run **hot** |
+| **Above baseline** | order holds; dispositions run **cool** |
+
+It is nudged by two events and, left alone, forgets.
+
+### The nudges
+
+| Event | Nudge |
+|---|---|
+| A crime, unanswered | **−0.08** |
+| Visible justice done (a punishment) | **+0.12** |
+
+Both stay clamped to the 0–1 range. Note the asymmetry: **punishment (+0.12) outweighs crime (−0.08)
+by 1.5×.** A colony that answers every offence does not merely break even — it ratchets *above*
+baseline into "order holds" territory. This is the deterrence dividend, and it is deliberate: justice
+seen to be done buys more order than the crime cost.
+
+The same crime that moves the climate also marks the culprit's record — the offence that shifts the
+colony's mood is the one classification and parole will remember later. A punishment moves only the
+climate; the reform side of a punishment — how the offender themselves changes — is
+[Discipline](Discipline-and-Reform.md)'s job.
+
+### The drift
+
+Memory fades. With nothing happening, the climate creeps back toward ordinary at about **0.0015 every
+in-game while (roughly one nudge every 2500 ticks)** — which works out to:
+
+**drift per in-game day ≈ 0.036**
+
+So a single unanswered crime (−0.08) takes roughly `0.08 / 0.036 ≈ 2.2 days` to heal on its own — or
+one punishment (+0.12) to over-answer instantly. An iron colony you stop maintaining slides back to
+baseline over about two weeks; it does not stay stern for free.
+
+---
+
+## The feedback — how it reaches every pawn
+
+This is the loop. The climate is read back into every colonist's upbringing as a multiplier on their
+propensity:
+
+| Order level | Factor | Effect on every pawn's disposition |
+|---|---|---|
+| 0.00 (lawless) | **1.300** | +30% hotter — crime pays, everyone feels it |
+| 0.30 | 1.120 | +12% |
+| **0.50 (baseline)** | **1.000** | **neutral — a default colony sits exactly here** |
+| 0.70 | 0.880 | −12% |
+| 0.90 | 0.760 | −24% |
+| 1.00 (iron) | **0.700** | −30% cooler — order holds, everyone calms |
+
+Two things to notice:
+
+- **Baseline is the neutral point, by design.** A default colony sits at 0.5, which is a factor of
+  exactly 1.0 — ordinary order neither inflames nor calms. That symmetry is deliberate. If baseline
+  ran hot, ordinary order would nudge propensity up, breed a little more crime, drop order, and feed a
+  slow runaway. Neutral-at-baseline means only a colony that lets order *slide below* ordinary earns
+  the hot multiplier, and only one that pushes *above* it earns the calm.
+- **The swing is 0.7× to 1.3×, symmetric around 1.0** — a ±30% spread applied to *everyone's*
+  disposition at once. This is the multiplier that makes catching one pawn matter to the disposition of
+  the rest.
+
+### When it applies
+
+This bending of behaviour only happens while **Policing is installed**. Core on its own reads a flat,
+neutral 1.0 — colonists are indifferent to order — and only Policing wires the climate into their
+disposition. A colonist who is off the map (in a caravan, in transit) has no local climate to read, so
+they fall back to neutral too.
+
+---
+
+## Worked example — a day at the institution
+
+The colony starts at baseline 0.5 (factor 1.05). Over one day:
+
+| Step | Event | Order level | Factor |
+|---|---|---|---|
+| start | — | 0.50 | 1.050 |
+| 1 | Prisoner A shanks a guard (crime, unanswered) | 0.42 | 1.106 |
+| 2 | Prisoner B foments trouble (crime, unanswered) | 0.34 | 1.162 |
+| 3 | Warden punishes A | 0.46 | 1.078 |
+| 4 | Warden punishes B | 0.58 | 0.994 |
+| overnight | nothing happens, drift ≈ −0.036 toward 0.5 | 0.544 | 1.019 |
+
+Two crimes cost −0.16; two punishments returned +0.24. The colony ends the day at 0.58 — **above**
+where it started — because punishment out-answers crime. Every pawn's disposition dipped hotter as the
+crimes landed (1.05 → 1.16) and then cooled below neutral once order was reasserted (0.994). By morning
+the drift has begun erasing the gain, and if nothing keeps the pressure on, the colony sinks back to its
+slightly-hot baseline over the next couple of weeks.
+
+That arc — hot when crime pays, cool when justice is seen, forgetful when neither happens — is the
+whole reason discipline is not inert. You are not punishing a pawn; you are setting the temperature of
+the room.
+
+---
+
+## How to play with deterrence
+
+- **Answer crime, visibly and promptly.** Each punishment is worth 1.5 crimes of order. A colony that
+  reliably punishes climbs *above* baseline and cools everyone; a colony that lets offences slide
+  sinks below and heats everyone — a spiral, because hotter pawns commit more crime.
+- **Don't coast on a past crackdown.** The climate drifts back to baseline at 0.036/day. Order is a
+  maintenance cost, not a one-time purchase.
+- **Push past baseline if you want calm.** Neutral disposition needs an order level of about 0.571;
+  ordinary (0.5) still runs 5% hot. A steady rhythm of caught-and-punished offences is what holds you
+  there.
+- **A lawless spell is self-feeding.** At an order level of 0.3 every pawn is 1.19× more disposed; more
+  crime follows, driving the level lower still. Break the cycle with punishments, not patience.
+
+---
+
+*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs · Ward.*

policing/Home.md

@@ -0,0 +1,53 @@
+# Institution: Policing
+
+*The enforcement and order layer — the pre-arrest half of the law — of the **Institution** suite of
+RimWorld 1.6 mods.*
+
+Vanilla RimWorld keeps a rap sheet no one reads, and your own colonists never break the law. Policing
+gives the colony a **climate of law and order**: colonists offend on a spectrum of criminal
+propensity, the law catches them, and catching one changes how the rest behave.
+
+> **Catching and punishing one pawn changes the disposition of the rest.**
+
+That is the difference between enforcement that *cleans up* and enforcement that **governs** — the
+reason to punish an offender is the message it sends everyone else quietly deciding whether crime pays.
+
+---
+
+## The pages
+
+| Page | What it covers |
+|---|---|
+| **[Policing](Policing.md)** | Colony crime on the propensity spectrum, witnesses and the constable's investigation, the weighed arrest and resisting it, prison riots, and the recidivism alert. |
+| **[Deterrence](Deterrence.md)** | The colony's climate of order (0 lawless … 1 iron), moved by crime and punishment, drifting back to baseline, and fed back into every colonist's disposition. |
+
+The climate of order only steers your colonists while Policing is installed. Core on its own keeps the
+records but leaves behaviour untouched; add Policing and the feedback loop comes alive — visible
+justice starts calming the colony, unanswered crime starts emboldening it.
+
+---
+
+## The one shared record
+
+Policing keeps no crime record of its own. It reads and writes the single criminal record that
+**Institution: Core** holds for every colonist — the same rap sheet Contraband, Corrections, and the
+gang systems read. A crime here adds to that record; Corrections grades and reforms over the same
+history.
+
+---
+
+## Requirements & load order
+
+- **RimWorld 1.6**
+- **Institution: Core** — required (the propensity and record system)
+- **Harmony** — required
+- Load **after** Core and Harmony.
+
+The prison half — classification, discipline, reform, parole, regime — lives in **Institution:
+Corrections**, which depends on this layer for the shared climate of order. A future **Judiciary** layer
+— a court that tries and sentences — is planned; for now an arrest sends the culprit straight to a cell.
+
+---
+
+*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs
+· Ward. Split out of the former Institution: Justice.*

policing/Policing.md

@@ -0,0 +1,114 @@
+# Policing — the pre-arrest half
+
+*The other half of the loop. Where the rest of Justice deals with people the colony has already
+caught, **policing** is what happens before the cell door: your own colonists commit crimes on the
+propensity spectrum, the colony investigates, and — sometimes — arrests.*
+
+It is a big behavioural change (your colonists become potential criminals), so it has **its own
+toggle** in the mod settings, on by default. Turn it off to run the rest of Justice — classification,
+deterrence, discipline, parole, regime — without colony crime.
+
+---
+
+## The loop
+
+**crime → witnessed / investigated → weighed arrest (resist?) → prison → … → parole → recidivism**
+
+Every stage draws on the same shared systems — each colonist's propensity, the one shared criminal
+record, the climate of order — so policing is not a bolt-on: the record it writes is the record
+classification grades on and discipline reforms.
+
+## Crime — and why small colonies stay honest
+
+Every ~40 seconds, each free colonist gets a hidden roll to offend. The base chance is low (about
+6% per roll) and it is multiplied hard by nature × nurture — almost nobody with an ordinary
+disposition ever does anything. But it is *also* multiplied by **crime cover**:
+
+| Free colonists | Crime cover |
+|---|---|
+| ≤ 3 | 0.15 |
+| ~8 | ~0.6 |
+| ≥ 13 | 1.0 |
+
+In a tight 2–3 pawn colony everyone knows everyone and retribution is certain even without a jail, so
+crime is **rare**; a larger, more anonymous colony offers cover. This is a deliberate inversion of the
+naive "no enforcement → more crime": a small colony is kept honest by its own closeness, not by a
+constable.
+
+A crime is one of **theft**, **vandalism**, or **assault** — leaning on who the culprit is (a
+kleptomaniac steals, a bloodlusty pawn assaults, a pyromaniac vandalizes).
+
+## Consequences — the stakes
+
+A crime leaves a mark the colony can *see*:
+
+- **Theft** lifts a small stack of the colony's goods and the thief **pockets it**. RimWorld has no
+  per-person property (stockpiles are communal), so theft is theft from the common store — but the
+  culprit now physically carries what they took, a natural evidence trail a search can pick up.
+- **Vandalism** damages a nearby colony building.
+- **Assault** gives a nearby colonist a light, down-safe knock — and the culprit chooses their mark
+  **wisely**: someone they resent (motive), who is weak (little retribution), and unwatched (few
+  witnesses).
+- **Relationships fray.** An assault victim thinks much worse of their attacker immediately (they saw
+  who did it); and when investigation *names* a culprit, the whole colony's opinion of them drops.
+- The colony is **notified** a crime happened — culprit unknown.
+
+## Witnesses and investigation
+
+A crime is not equally solvable. Colonists who were near enough to **see** it are witnesses, and each
+is a partial lead — a witnessed crime starts up to 80% of the way to solved before anyone lifts a
+finger; an unseen one is a **cold case** worked from nothing.
+
+Investigation then builds evidence toward a full, named solve two ways:
+
+- **Ambient** progress, scaled by how many colonists the colony can spare — a background trickle from
+  everyone keeping an eye out, faster when the colony has people to spare.
+- **The policing work type.** Assign a colonist to *policing* and they walk to open **crime scenes**
+  and work them, adding a chunk of evidence scaled by their Intellectual + Social skill. A sharp
+  constable cracks cases fast; a colony that spares no one lets them go cold.
+
+## The weighed arrest
+
+A solved case does **not** mean an automatic arrest. Fellow-colonist cops will not gut the colony to
+jail someone over a petty crime — the arrest is a cost/benefit call, and it goes ahead only when both
+are true: the colony can **afford a prison**, and the crime is **serious enough** to clear a bar that
+rises with how valuable the culprit is.
+
+- **Severity** — the crime's kind (theft 1 · vandalism 1.5 · assault 2.5), escalated by the culprit's
+  record (a rap sheet and prior escapes compound).
+- **Value** — 0..1 from the culprit's best skills. The bar sits at about 1.5 for an expendable pawn
+  and climbs by three times the culprit's value — so a star colonist raises it to about 4.5.
+- **Capacity** — **below ~5 colonists, or with no prison bed, the colony arrests no one.** A prisoner
+  plus a warden would cripple a small colony. Capacity ramps up as the colony grows.
+
+So a petty crime by your only doctor → they walk. A murder → arrested regardless. And a crime that
+paid, unanswered, erodes the climate of order a little more (crime emboldens).
+
+## Resisting arrest
+
+The disposed do not go quietly (seeded by nature × nurture):
+
+- **Comply** → taken in cleanly (they become a prisoner of the colony — imprisonment is direct, and it
+  survives guest-management mods like Hospitality).
+- **Resist** → the violent turn **berserk**, the rest **flee**. A botched arrest becomes a crisis the
+  colony must handle the hard way, and openly defying arrest emboldens the lawless.
+- **Subdued** → a resister the colony beats down is then **imprisoned** — the resist path resolves to a
+  cell once the colony wins the confrontation. One who flees the map gets away.
+
+## Prison riots
+
+When the climate of order **collapses** (deterrence at the floor) in a colony holding prisoners, a
+neglected prison boils over into a **riot**: disposed prisoners turn violent together, and the unrest
+shatters order further. A well-run colony (high deterrence) never sees one — a riot is the thing a
+badly-run institution *earns*.
+
+## Recidivism, made visible
+
+The loop closes on itself: a pawn hardened in prison (negative reform) runs a higher propensity and
+reoffends. When investigation names a culprit the colony had **paroled**, it says so out loud — the
+recidivism loop turning in the open, the payoff for everything classification, discipline, and parole
+did upstream.
+
+---
+
+Part of **Institution: Policing**, in the Institution suite.

ward/Home.md

@@ -0,0 +1,93 @@
+# Institution: Ward
+
+**Involuntary psychiatric commitment for RimWorld 1.6 — the third pawn state, neither free nor guilty.**
+
+> **The psychiatric-care layer of the [Institution](https://git.onetick.ninja/flan/rimworld-institution)
+> suite.** Ward runs on Core's shared treatment engine and ships bundled in the single Institution
+> install with a toggle of its own; it still installs standalone (needing only Institution: Core and
+> Harmony). Once a separate sister mod, now folded in.
+
+RimWorld gives a person exactly two places to stand: **colonist**, or **prisoner**. There is no
+third state for someone who is neither free nor guilty. Out of the box you cannot commit anyone. A
+colonist breaks, wanders off, punches a wall, recovers on their own, and goes back to hauling steel
+as though nothing happened. Mental breaks are episodic and amnesiac — nothing persists, nothing is
+*done* about them.
+
+Ward adds the missing state, and the room to put it in. A colonist you arrest can be set to
+**psychiatric care**. Wardens counsel them at a **treatment station**. A room with prisoner beds
+and a treatment station is a **psychiatric ward**, not a prison cell. Treatment lowers the patient's
+mental-break threshold while it lasts — and it fades, so it has to be *sustained*. A ward you don't
+staff is worse than no ward at all.
+
+---
+
+## The third state RimWorld doesn't have
+
+The reason "commit a colonist" isn't a stock button is simple: vanilla only knows two kinds of held
+person — a free colonist and a prisoner. There's no built-in slot for someone who is neither free nor
+guilty, which is why other mods that keep a not-quite-colonist around (like *Hospitality* and its
+guests) have to work so hard to maintain them.
+
+**Ward takes the cheap road.** A committed pawn *is* a prisoner — arresting your own colonist already
+does that. Ward just adds a new **way to handle** that prisoner: a "psychiatric care" mode you toggle
+on, sitting alongside vanilla's recruit / convert / release options. Nothing exotic — it's the same
+kind of custom prisoner mode other prison mods already add.
+
+So committing someone is entirely ordinary from the game's point of view:
+
+- **psychiatric care** — a new prisoner interaction mode you switch on
+- **the psychiatric ward** — a new room role a cell earns once it holds a treatment station
+- **counselling** — a new warden job, handled like any other warden work
+- the **treatment station**, the **recovery**, the **neglect** — new content layered on top
+
+Because Ward *adds* things rather than rewriting how vanilla prisoners behave, it sits quietly next to
+the popular psych and prison mods instead of fighting them. Which mods, and why, is on the
+**Compatibility** page.
+
+---
+
+## Riding the prisoner rail (why the suite cares)
+
+The choice that makes Ward *cheap* also makes it *interesting* inside the wider Institution suite. A
+committed patient is a genuine vanilla prisoner. That means they're a **held pawn** in exactly the
+sense the rest of the suite understands: someone who can be searched, and who can conceal and
+improvise contraband. A patient in a psych ward can hoard a shiv or brew something foul in a smuggled
+vessel, because the contraband, search, corruption and gang systems already work on any held
+prisoner — and a ward patient is one, for free.
+
+**And re-labelling a cell as a ward never lets anyone out.** A ward is a prison cell that also happens
+to be a ward — the two roles coexist. Containment, food delivery, and prison breaks all keep working
+exactly as they did before you built the station.
+
+---
+
+## Wiki index
+
+| Page | What's on it |
+|---|---|
+| **Home** (this page) | What Ward is, the third-state problem, the suite |
+| **Commitment** | How commitment works in play: the care mode, the station, the ward room, the warden's job, treatment, recovery, neglect, and how it stacks with recruitment — with the real numbers |
+| **Compatibility** | Which popular psych and prison mods Ward plays nicely with, and why it doesn't fight them |
+
+---
+
+## Part of the Institution suite
+
+A set of RimWorld 1.6 mods about what an institution does to the people inside it. Each mod stands
+alone as an install; together they interlock into one system — colonists and prisoners drift toward
+crime on a spectrum of nature × nurture, and a policing/justice layer discovers, catches, punishes,
+reforms, or paroles them. Ward's psychiatric ward is a secure context where a committed patient can
+conceal and improvise contraband exactly as a prisoner can, because they ride the same prisoner rail.
+
+| Mod | What it is |
+|---|---|
+| **Institution: Ward** (this) | Involuntary psychiatric commitment — the third pawn state, neither free nor guilty. |
+| **Institution: Core** | The shared engine — propensity (nature × nurture), the criminal record, secured context. |
+| **Institution: Contraband** | The physical smuggling loop — conceal, improvise shivs, dig Prison-Architect tunnels, warden search, warden corruption. |
+| **Institution: Justice** | Corrections & policing — classification, deterrence, discipline, parole, regime. |
+| **Institution: Gangs** | Gangs as contraband economies — joining, smuggling networks, rivalry, fights-as-crime. |
+| **Foul Play** | The vessel + substance + throw framework, and the "Piss Nuke" flagship; bridges to Core + Contraband when both are present. |
+
+Reference sibling mods by name — the mods are separate repositories and cross-repo links break.
+
+---