pdComp Custom Catalogs
======================

pdComp loads custom catalogs from:

Plugins/LSPDFR/pdComp/data/charges.json
Plugins/LSPDFR/pdComp/data/citations.json
Plugins/LSPDFR/pdComp/data/court_personnel.json

Edit these files to replace, remove, or add charges/citations/personnel. The files are
loaded when pdComp starts. pdComp tries to keep imperfect custom rows by filling
safe defaults for missing optional fields. A row is skipped only when it does not
have enough text to display.

Charge and citation category headers appear in the order their category first
appears in the JSON file. Rows within a category keep their JSON order.


CHARGES.JSON
------------

The file must look like this:

{
  "charges": [
    {
      "code": "PC.240",
      "description": "Assault",
      "severity": "Misdemeanor",
      "category": "Crimes Against a Person"
    }
  ]
}

The object form above is recommended. For simple custom charge-only files,
pdComp also accepts a top-level JSON array of charge rows.

Strongly recommended charge fields:

code          Statute/code shown in the UI. Example: PC.245(a)(1)
description   Short charge name.
severity      Must be Infraction, Misdemeanor, or Felony.

If code is missing, pdComp uses statute or generates CUSTOM.CHARGE.###.
If description is missing, pdComp uses notes, courtNotes, statute, or code.
If severity is missing or slightly misspelled, pdComp infers from legalClass,
tier, wobbler, and text, then defaults to Misdemeanor. "Misdemeanour" is accepted.

Recommended charge fields:

category       Broad group such as Property Crimes, Weapons, or Public Justice.
tier           Court severity from 1 to 5.
legalClass     Infraction, Misdemeanor, Wobbler, Felony, Serious Felony, etc.
statute        Human-readable statute. Example: PC 245(a)(1)
notes          User-facing "when to apply this charge" note shown in the catalog.
courtNotes     Short legal/court note used for court context.
wobbler        true if the charge can be misdemeanor or felony.
seriousFelony  true for serious felony handling.
violentFelony  true for violent felony handling.
modifiers      Optional selectable charge facts.
enhancements   Optional sentencing add-ons.

Court tiers:

1 = cite/release, infraction, low fine, minor record
2 = standard misdemeanor
3 = aggravated misdemeanor, wobbler, or low felony
4 = serious felony
5 = violent or major felony

If tier is missing, pdComp uses:

Infraction  -> tier 1
Misdemeanor -> tier 2
Felony      -> tier 3

For custom felonies, wobblers, violent charges, and serious charges, set tier
yourself so the court system can sentence them correctly.


MODIFIERS
---------

Modifiers let one charge cover several versions of the same offense.

Example:

{
  "id": "deadly_weapon",
  "label": "Deadly weapon involved",
  "group": "assault_variant",
  "code": "PC.245(a)(1)",
  "description": "Assault with a deadly weapon",
  "severity": "Felony",
  "tier": 3,
  "legalClass": "Wobbler",
  "wobbler": true,
  "statute": "PC 245(a)(1)",
  "courtWeight": 4,
  "notes": "Raises the filing into wobbler/felony handling."
}

Important modifier fields:

id            Recommended. Unique within that charge; generated if missing.
label         Checkbox label shown to the user.
group         Optional. Modifiers in the same group are mutually exclusive.
code          Optional replacement code.
description   Optional replacement description.
severity      Optional replacement severity.
tier          Optional tier increase/override.
courtWeight   Extra seriousness for court. Usually 1 to 6.
notes         Short context note.


ENHANCEMENTS
------------

Enhancements are sentencing add-ons.

Example:

{
  "id": "firearm_use",
  "code": "PC.12022.5",
  "label": "Personal firearm use",
  "statute": "PC 12022.5",
  "tierDelta": 1,
  "courtWeight": 5,
  "sentenceMonths": 36,
  "trueEnhancement": true
}

Useful enhancement fields:

id              Recommended. Unique within that charge; generated if missing.
code            Enhancement code shown beside the charge.
label           Checkbox label shown to the user.
statute         Human-readable statute.
tierDelta       Adds to the final tier. Usually 0 or 1.
courtWeight     Extra seriousness. Usually 2 to 8.
sentenceMonths  Added sentence exposure.
notes           Short context note.


CITATIONS.JSON
--------------

The file must look like this:

{
  "citations": [
    {
      "code": "VC.22350",
      "description": "Basic speed law: unsafe speed for conditions",
      "fine": 238,
      "category": "Speeding"
    }
  ]
}

The object form above is recommended. For simple custom citation-only files,
pdComp also accepts a top-level JSON array of citation rows.

Strongly recommended citation fields:

code          Citation/statute code.
description   Short citation name.

If code is missing, pdComp uses statute or generates CUSTOM.CITE.###.
If description is missing, pdComp uses notes, statute, or code.

Recommended citation fields:

fine                Gameplay fine amount.
category            Broad group such as Speeding, Parking, or Public Order.
statute             Human-readable statute.
points              DMV-style points. Use 0 for non-moving citations.
correctable         true for fix-it tickets.
enforcementType     Traffic, Parking, Fix-It, Criminal Cite, Municipal, or Fish and Game.
appearanceRequired  true if the cite should require court handling.
notes               Short context note.

If enforcementType is missing, pdComp guesses from category/code:

correctable true             -> Fix-It
category contains Parking    -> Parking
category contains Municipal  -> Municipal
category contains Fish/Game  -> Fish and Game
Public Order/Reckless/DUI    -> Criminal Cite
everything else              -> Traffic


COURT_PERSONNEL.JSON
--------------------

This file controls the pool of judges, prosecutors, and defense counsel that
pdComp can automatically assign to new court cases. Users do not pick personnel
case-by-case from the docket.

The file must look like this:

{
  "judges": [
    {
      "name": "Hon. Mara Castillo",
      "style": "Balanced Proceduralist",
      "tendency": "Keeps the record clean and rarely swings hard.",
      "department": "Dept. 2A",
      "convictionBias": 0,
      "pleaBias": 1,
      "dismissalBias": 0,
      "acquittalBias": 0,
      "sentenceMultiplier": 1.00
    }
  ],
  "prosecutors": [],
  "defenseCounsel": []
}

Required personnel fields:

name      Display name. Keep it unique within judges/prosecutors/defenseCounsel.

Recommended personnel fields:

style               Short personality label shown in court details.
tendency            One-sentence flavor note.
department          Judge department/courtroom. Judges only.
convictionBias      Positive favors conviction, negative weakens it.
pleaBias            Positive favors plea deals.
dismissalBias       Positive favors dismissals.
acquittalBias       Positive favors acquittals/not guilty outcomes.
sentenceMultiplier  Sentencing nudge. 0.90 is lighter, 1.10 is harsher.

Keep bias values modest. Good ranges are -5 to +5 for normal personalities and
-8 to +8 for extreme personalities. pdComp clamps outliers so one custom row
cannot break the court system.


HOW COURT LOGIC USES CUSTOM FILES
---------------------------------

The court system looks at:

- charge tier
- legal class
- modifiers and enhancements
- courtWeight
- citation enforcementType
- citation points/correctable/appearanceRequired
- repeat history
- charge count
- evidence quality
- defense counsel type
- judge/prosecutor/defense counsel styles from court_personnel.json

Missing evidence does NOT automatically hurt every charge.

It only hurts when the charge appears evidence-dependent and the arrest report
narrative is thin. Simple officer-observed charges can still work normally
without linked evidence.

Evidence-dependent words include:

drug, controlled substance, firearm, weapon, stolen, theft, burglary, fraud,
forgery, identity, embezzlement, arson, computer, sexual, child abuse, domestic,
great bodily injury, homicide

Observation/report-based words include:

resisting, obstruction, trespass, disturbing, public intoxication, failure to
obey, reckless driving


QUICK COMPATIBILITY CHECKLIST
-----------------------------

1. Keep valid JSON. Do not put comments in .json files.
2. Use the root key "charges", "citations", "judges", "prosecutors", or "defenseCounsel".
   Charge and citation files may also be a top-level array of rows.
3. Give every charge code, description, and severity for clean display.
4. Give every citation code and description for clean display.
5. Use broad, consistent categories.
6. Set tier on felonies, wobblers, serious felonies, and violent felonies.
7. Use modifiers instead of duplicating many near-identical charges.
8. Use enhancements for sentencing add-ons.
9. Keep courtWeight modest.
10. Use citation/personnel metadata when the automatic defaults are not enough.
11. There is no hard limit on custom charges or citations; large lists are best
    managed with clear categories and searchable descriptions.


COMMON MISTAKES
---------------

- Adding comments inside JSON.
- Making every felony tier 5.
- Giving every enhancement a large tierDelta.
- Using many tiny categories that break repeat-history matching.
- Reusing the same modifier id inside one charge.
- Forgetting that modifiers in the same group are mutually exclusive.
- Giving every judge/prosecutor/defense profile extreme bias values.
- Leaving out every display field. pdComp can generate code/severity defaults,
  but it still needs a description, notes, statute, or code to show the row.
