Institution suite hub: master roadmap + overview

The suite-level home: the thesis (crime spectrum, nature x nurture, policeable),
the secured-context principle (prisoner/ward/slave/secure-area), all seven module
slots, the full crime loop, build order, prior-art verdicts, and the standing
rules -- self-complete and dependency-free, coexist-don't-duplicate judged by
quality not sub count, extend by capability not list.

README.md

@@ -0,0 +1,52 @@
+# 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. Each mod stands alone and requires none of the
+others; together they form one system.
+
+## The thesis
+
+> Every pawn has a criminal propensity on a spectrum — **nature** (traits) × **nurture**
+> (circumstance, mood, treatment) — and the colony can **police** it.
+
+The suite is the two halves of that: colonists commit crimes and a policing layer catches them
+(pre-arrest), and prison / contraband / wards / secure areas hold and reform them (post-arrest).
+Arrest is the hinge. Nothing hard-codes "prisoner" — every held-person system keys off a
+**secured context**: prisoner, ward patient, slave, or secure-area occupant.
+
+## The mods
+
+| Mod | What it is | Status |
+|---|---|---|
+| [Foul Play](https://git.onetick.ninja/flan/rimworld-foulplay) | throw a container of something off a body; vessels + substances + the **Piss Nuke** flagship | shipping |
+| [Institution: Contraband](https://git.onetick.ninja/flan/rimworld-contraband) | conceal / improvise / search / confiscate; intake, escape, secure areas | building |
+| [Institution: Ward](https://git.onetick.ninja/flan/rimworld-ward) | involuntary psychiatric commitment — the third pawn state, neither free nor guilty | shipping |
+| Institution: Regime | daily schedule (vanilla Restrict) + modest needs + visitation | planned |
+| Institution: Justice | the crime loop, the policing officer, parole / discharge / manumission | planned |
+| Institution: Discipline | security classification, punishment-as-order, corruption | planned |
+| Institution: Gangs | prisoner & colony gangs, rivalries, contraband networks | planned |
+
+## Principles
+
+- **Self-complete, dependency-free.** Every mod works alone; none requires another suite mod or any
+  third-party mod. Integrations are always `MayRequire`-soft — features light up if a mod is
+  present and the loop still closes without it.
+- **Coexist, don't duplicate.** We test against the all-time most-subscribed Workshop mods and
+  never rebuild what a genuinely good mod already does well — judged by quality, not sub count.
+- **Extend by capability, not by list.** New content registers via `IsWeapon` / `IsDrug` /
+  category, so modded items are covered without being named.
+
+## The plan
+
+The full design, module scope, build order, and prior-art verdicts are in
+[ROADMAP.md](ROADMAP.md). Per-mod roadmaps live in each repo (e.g. Contraband's item build list).
+
+## Compatibility
+
+The harness (`Tools/run-compat-test.sh` in the Ward repo) boots a real headless RimWorld with the
+suite plus the popular psych/prison mods **and** the all-time most-subscribed mods loaded at once,
+and fails on any error naming our code. Combat Extended gets its own dedicated pass.
+
+## AI disclosure
+
+Designed and built with substantial assistance from Claude (Anthropic).

ROADMAP.md

@@ -0,0 +1,282 @@
+# The Institution suite — master roadmap
+
+A set of RimWorld mods about **what an institution does to the people inside it** — and the crime,
+policing, and justice that put them there. Each mod stands alone; together they form one system.
+
+## North star
+
+> **Every pawn has a criminal propensity on a spectrum — nature (traits) × nurture (circumstance,
+> mood, treatment) — and the colony can police it.**
+
+The same seeded disposition engine that drives the piss spree (`WouldFoulPeople` = disposition ×
+circumstance, fixed per pawn), generalized. The suite is the two halves of that:
+
+- **Pre-arrest** — colonists commit crimes on a spectrum; a policing layer discovers, investigates,
+  and catches them. Arrest is the hinge.
+- **Post-arrest** — prison, contraband, improvised weapons, escape, wards, secure areas, the daily
+  life of the held, and the path back out (parole / discharge / manumission).
+
+## The load-bearing principle: SECURED CONTEXT, not "prisoner"
+
+Nothing hard-codes "prisoner." The subject of every held-person system is a **secured context** —
+a pawn held in a controlled space, subject to search, following a regime:
+
+| Context | Members | Authority | Release path |
+|---|---|---|---|
+| Prison | prisoners | warden | **parole** |
+| Psych ward (Ward mod) | committed patients | orderly / warden | **discharge** (when treated) |
+| Slavery (Ideology) | slaves | overseer | **manumission** (Ideology) |
+| Secure area | anyone inside a zone | assigned guard | leave the zone |
+
+A committed patient rides the vanilla prisoner rail (Ward's `Ward_PsychiatricCare` mode), so
+contraband, search, schedule, needs, and visitation **already apply to ward patients for free** —
+and to slaves via a small Ideology-gated extension. Every system below reads
+`SecuredContextOf(pawn)`, never `IsPrisonerOfColony` directly. Build prisoner-first, against the
+predicate, and ward + slave + secure-area fall out without a rewrite.
+
+Design tone: **standards are low on the rim.** Needs and expectations for the held are modest — a
+prisoner does not expect a spa. Don't over-model comfort; a little goes a long way.
+
+---
+
+## Suite modules
+
+| Mod | Scope | Status |
+|---|---|---|
+| **Foul Play** | throw a container of something off a body; vessels + substances + Piss Nuke flagship | built |
+| **Institution: Contraband** | conceal / improvise / search / confiscate / intake / escape / secure-areas | building |
+| **Institution: Ward** | involuntary psychiatric commitment — the third pawn state | built |
+| **Institution: Regime** | daily schedule (vanilla Restrict) + modest needs + visitation, for every secured context | planned |
+| **Institution: Justice** | the crime loop (commit → discover → investigate → attribute → arrest), policing officer, parole/discharge/manumission | planned |
+| **Institution: Discipline** | security classification / segregation, punishment-as-order, corruption | planned |
+| **Institution: Gangs** | prisoner & colony gangs, rivalries, contraband networks | planned |
+
+Seven mods is the ceiling. Prefer folding a slot into an existing module over minting a new one.
+
+---
+
+## Regime — daily life of the held
+
+### Schedule (use vanilla, don't reinvent)
+
+RimWorld already has `Pawn_TimetableTracker` + `TimeAssignmentDef` and the Restrict tab. **Extend
+that to secured pawns** rather than building a new regime UI. Prison Labor (`1899474310`, 176k)
+already puts force-to-work prisoners in the Restrict grid — build on that pattern, don't fight it.
+
+- Give secured pawns a timetable; surface it in the Restrict tab.
+- Two new `TimeAssignmentDef`s cover the prison-specific blocks vanilla lacks: **Yard** (go to a
+  designated yard/commons — ties to Prison Commons) and **Lockup** (confined to cell). Eat/Sleep/
+  Work/Joy map to existing assignments.
+- A think-tree branch makes secured pawns honour their timetable (they already have a prisoner
+  think-tree branch to hook).
+- Ward routine and slave work-schedule are the same machinery, different default timetables.
+
+### Needs (modest — standards are low)
+
+Do NOT build a full Prison Architect needs sim. One or two low-stakes needs, keyed to the schedule:
+
+- **Yard / open air** — satisfied by the Yard block. Vanilla already has the Outdoors need; check
+  whether it applies to secured pawns and lean on it before adding one.
+- **Safety** — a modest mood factor from feeling safe (few violent cellmates, guards present).
+- Recreation is already covered by Prisoner Recreation (`815726158`) — don't rebuild.
+
+Keep the magnitudes small. A satisfied schedule = a quiet wing; neglect = the disposition engine
+tips more pawns over the edge (feeding contraband, breaks, gang recruitment).
+
+### Visitation
+
+Off-map visitors and related pawns visit the held. A genuine greenfield gap — Hospitality is
+guests only and never touches prisons.
+
+- A **visitation room** role; scheduled visiting hours (a schedule block).
+- A prisoner/patient with family or faction ties gets visits; the warden/orderly supervises.
+- Feeds a modest Family/social mood boost. **Thematically strongest for the ward** — a committed
+  patient's family visiting is exactly right — and it is a supply route for contraband (a visitor
+  smuggles something in → Contraband's conceal system).
+
+---
+
+## Justice — the crime loop (the missing middle)
+
+The heart. Without discovery + investigation, "crime" is just a random bad event, not something you
+police. The loop:
+
+**commit → discover → investigate → attribute → arrest → (held) → release**
+
+- **Commit.** A colonist acts on their propensity (nature: traits incl. VTE `2296404655` 646k
+  kleptomaniac/pyromaniac — *integrate as inputs, don't rebuild*; nurture: our stat). Crimes:
+  theft, contraband possession, sabotage, arson, assault, at the serious end murder.
+- **Discover.** The colony learns a crime happened: missing goods, a body, damage, filth, or a
+  **witness**. Discovery is not automatic — a crime in an unwatched place may go unnoticed.
+- **Witnesses / informants.** A colonist near the act may witness it → report, be intimidated
+  into silence, or inform for favour. The cheap, characterful detection layer.
+- **Investigate.** A policing officer works the scene: evidence, opportunity, the stolen goods in
+  someone's concealed stash (ties to Contraband search!), narrowing suspects.
+- **Attribute.** Evidence points to a pawn. Confidence, not certainty — wrongful accusation is a
+  possible, dramatic failure.
+- **Arrest.** Vanilla's one law verb. The hinge into the held systems.
+
+### Policing officer
+
+Guarding is owned (Guards For Me `1855885448`, 88k — patrol/bodyguard, external threats only), the
+*catching* is not. Build the officer who investigates and arrests criminal colonists; **lean on
+Guards For Me's guard role** where present rather than reinventing patrol.
+
+### Parole / discharge / manumission — release, driven by IDEOLOGY
+
+The payoff that makes Ward's treatment and good behaviour *mean* something. Release is not a flat
+timer — the colony's **Ideology precepts** decide the policy (`MayRequire` Ideology; a vanilla
+fallback for non-Ideology games):
+
+- A harsh / execution-favouring ideoligion rarely paroles (executes or works-to-death instead).
+- A rehabilitative / lenient ideoligion paroles readily on reform + good behaviour.
+- **Parole** (prisoner), **discharge** (ward patient, when treated — the Ward analog),
+  **manumission** (slave, Ideology's own freeing) are one mechanism with three faces.
+- A released, reformed pawn has **reduced recidivism** — integrate with Prisoner Realism's
+  recidivism (`3760196312`) rather than duplicate it: our reform lowers its return chance.
+
+Sentencing timers exist (Prisoner Sentencing `3736998871`) — defer to it; add only the
+ideology-driven *decision*, not another timer.
+
+---
+
+## Discipline — control
+
+- **Classification / segregation — make the wings players already build MEAN something.**
+  Players already hand-build min / medium / max / solitary blocks with zones, cells and locks.
+  RimWorld just has no notion of *who belongs where* or *whether they are correctly placed*. We do
+  not replace the building — we add the intelligence layer on top of it, and it becomes the
+  **router** that connects the whole suite:
+
+  - **Grade (information).** Each secured pawn gets a risk grade computed from disposition × traits
+    × history (escape attempts, contraband made, guards attacked, murder on record). The player
+    stops guessing who is dangerous — the game tells them "this one is max."
+  - **Assignment + misplacement flag (enforcement).** Tag a wing's grade; the system routes
+    prisoners to the matching wing and **warns** when a max-grade pawn sits in a min cell. Vanilla
+    gives zero feedback here today.
+  - **Dynamic re-classification (dynamics).** Grade moves with behaviour: an escape attempt or a
+    shanking **upgrades** them; Ward treatment + good conduct + time **downgrades** them. This
+    wires classification straight into the behaviour loop.
+  - **Grade gates the other systems (the payoff).** Grade drives search frequency (Contraband —
+    max = frisked often), privileges (Regime — yard/visitation/recreation restricted by grade),
+    escape risk (a dangerous pawn in a weak cell escapes more), and reform eligibility (Justice).
+  - **The tension that makes it a decision.** Over-classify (everyone in max/solitary) = safe but
+    mood craters, reform fails, ideology frowns on cruelty, and warden-hours explode.
+    Under-classify (everyone min) = cheap and happy but they walk out. Classifying *correctly* is
+    the game; we supply the information and the consequences that make it one.
+
+  No mod auto-classifies (manual wing-building is emergent player behaviour, not a mod), so the
+  *system* is an uncontested gap even though the physical tiers are common.
+- **Punishment as a player order.** Issue solitary / lockdown / privilege-revocation as a
+  discipline *action*. Distinct from Prisoner Realism's *passive* solitary toll — we add the
+  order and its interface; defer the mood consequence to Realism where present.
+- **Corruption.** Wardens/guards take bribes, smuggle, or look away — a guard-integrity stat. Seeds
+  the bent-warden contraband supply route already in Contraband's plan.
+
+---
+
+## Gangs
+
+Untouched by any mod. Prisoners (and colonists) form gangs / factions with rivalries that drive
+violence and run contraband networks. Ties to disposition (who joins), contraband (what they move),
+and classification (segregate rivals). The richest, latest module — build after the loop works.
+
+---
+
+## Build order (fills the meta-gap: don't build it all at once)
+
+1. **The crime loop core** — discover + witnesses + investigate + attribute. Without it the whole
+   crime thesis is inert. Build *before* individual crime types.
+2. **Regime** — schedule (vanilla Restrict) + one or two modest needs. Cheap, high-value, and it
+   feeds the disposition engine (neglect → crime).
+3. **Visitation** — greenfield, thematically strong for the ward, doubles as a contraband route.
+4. **Parole / discharge / manumission** — gives Ward and good behaviour a payoff; ideology-driven.
+5. **Classification**, then **punishment-orders**, then **corruption**.
+6. **Gangs** — last; needs the rest in place.
+
+Already in flight (Contraband/Foul Play): hooch, improvised weapons, fire-starter, escape tools,
+intake search, secure areas. See [Contraband ROADMAP](https://git.onetick.ninja/flan/rimworld-contraband).
+
+## Compatibility — the non-negotiable
+
+The suite must load and run cleanly alongside the **all-time most-subscribed Workshop mods**, not
+just prison-adjacent ones — that is the load order most players actually run. The harness
+(`Tools/run-compat-test.sh` in the Ward repo) boots a real headless RimWorld with the suite plus
+this stack loaded at once and fails on any error naming our code.
+
+Baseline stack (all 1.6, verified subs):
+
+- **Frameworks:** Harmony (3.2M) · HugsLib (2.5M) · Vanilla Expanded Framework (2.0M) · Humanoid
+  Alien Races (1.1M).
+- **Ubiquitous gameplay/AI:** Pick Up And Haul (1.7M) · Common Sense (1.05M) · Simple Sidearms
+  (954k) · Vanilla Furniture Expanded (1.08M) · EdB Prepare Carefully (1.67M).
+- **UI (load-order neighbours):** RimHUD (1.5M) · Allow Tool (1.36M) · Interaction Bubbles (1.15M)
+  · Camera+ (997k).
+- **Weapon/our-domain risk:** Vanilla Weapons Expanded (985k) · VFE Furniture Security (865k) ·
+  Vanilla Brewing Expanded (589k) · Hospitality (798k).
+- **Prison-adjacent (design overlap):** Prison Labor · Prison Commons · Locks · Restraints ·
+  Custom Prisoner Interactions · Prisoner Realism · Prisoner Recreation · Dubs Bad Hygiene ·
+  Psychology · Rim Disorders · More Mental Breaks.
+
+**Combat Extended** (387k, 1.6) gets its OWN dedicated pass, not the mixed stack: it overhauls
+verbs, projectiles, damage and armour — exactly our thrown-weapon surface — so an ambiguous
+failure in a 25-mod stack would be useless. Loading-clean-under-CE is a must-have; a tuned CE
+armour-penetration patch (`MayRequire`) is a strongly-recommended follow-up, not a release blocker.
+
+How the suite earns this: zero-Harmony cores, Contraband optional via a `LoadFolders` bridge, every
+DLC/mod tie-in `MayRequire`-gated, and new content registered by capability (`IsWeapon`, `IsDrug`,
+category) rather than hard-coded lists — so modded weapons, drugs and races are covered without
+being named.
+
+## Self-complete, dependency-free — the standing rule
+
+Two rules, and the second is the sharper one:
+
+1. **Judge by QUALITY, not sub count. If an incumbent is actually good, keep it.** A genuinely
+   good mod — even a small one — is worth coexisting with rather than rebuilding: don't waste
+   effort duplicating something done well (Prisoner Realism at 11k is a *good* deep sim → keep
+   it). Only build our own where the incumbent is **thin, absent, or mediocre** on one of our
+   crucial loops (Prisoner Recreation just flips vanilla Joy → trivially ours; the 334-sub crime
+   mod is niche → the slot is open). Sub count is a hint, not the test.
+
+2. **No hard dependencies. Every crucial loop is self-complete.** The suite must be a whole,
+   working system on its own. Third-party mods are **coexistence targets that ENHANCE**, never
+   requirements. Where we integrate (Ideology precepts, Prisoner Realism's recidivism, Prison
+   Labor's regime), it is always `MayRequire`-soft: the feature lights up if the mod is present
+   and the loop still closes without it.
+
+What this changes vs. a naive "defer to whoever got there first":
+
+- **Recreation is ours to enable.** Prisoner Recreation (38k) and Prisoner Realism (11k) ship no
+  custom need — they just flip on the *vanilla Joy need* for prisoners. We do the same in our
+  needs system: idempotent, coexists, zero dependency, no citing.
+- **Release-outcome / recidivism** — build a modest self-complete version (reformed → less return;
+  abused → returns hostile). Prisoner Realism's deeper recidivism coexists; we don't require it.
+- **Solitary/isolation consequence** — a light version of our own so Discipline is self-complete;
+  Realism's deeper toll coexists.
+- **Escape** is already self-complete: vanilla mental-break breaks + our disposition-driven arming
+  + our patient tunnel. Realism's lockpick/ringleaders are enhancements on top, not gaps we leave.
+
+Genuinely leave alone (giant + redundant + not a gap in our loops): forced labor (Prison Labor
+176k), hygiene (Dubs Bad Hygiene 632k), crime *traits* (Vanilla Traits Expanded 646k — we consume
+them as nature inputs), guest hosting (Hospitality 798k). Coexist with all; depend on none.
+
+### Prior-art sweeps done (2026-07-14/15)
+
+Uncontested gaps, safe to build clean: contraband/search, improvised weapons, keep-inventory
+intake, secure-area search, nurture criminality stat, investigating officer, patient escape,
+visitation, classification, punishment-order, gangs, corruption. Partial (build the uncovered
+slice only): prisoner timetable, yard/safety/privacy needs, evidence/forensics investigation,
+active snitch/informant, reform-and-ideology-driven parole. The only prior art in the
+crime/parole space (Rimworld Law and Order, 334 subs) fails the *popular* bar, so that slot is
+open — build it without duplicating that niche mod exactly.
+
+## Architecture already honors rule 2
+
+Zero hard dependencies anywhere: Foul Play stands alone, Contraband is optional to it (the
+`LoadFolders` bridge loads only when both are present), Ward stands alone, and every DLC/mod
+tie-in is `MayRequire`. No suite mod requires another suite mod or any third-party mod.
+
+## AI disclosure
+
+Designed and built with substantial assistance from Claude (Anthropic).