Feature overview for garrison upkeep.
BETA - Still in beta and disabled by default, enable in mct settings.
The feature is subject to change based on user feedback, so please leave any suggestions you have in the comments.
The feature is safe to taggle at any time.

The garrison upkeep feature enables full upkeep for all garrison units but provides slots which free a unit from that upkeep.
These slots are provided by the settlement's regular buildings. (Foreign buildings are not taken into account)
Units are then sorted into these slots starting with the most expensive first.
Each slot has an associated tier and can be used by a unit of the same tier or lower.

The main settlement building provides a number of slots as a baseline, the slots tier is equivalent to the level of the main settlement building.
A fully upgraded minor settlement with a tier 3 main building will provide 5 tier 3 slots by default, this means that 5 units of tier 3 or lower will be free of any upkeep.
A major settlement with a tier 5 main building will provide 5 tier 5 slots by default, this means that 5 units of tier 5 or lower will be free of any upkeep.

Both defence and military buildings will provide free upkeep slots as well.
The amount of slots provided is based on the number of levels in the chain.
The tier of slots is the settlement tier required for the building.
This means that a tier 2 empire barracks will provide 3 tier 2 slots, as there are 3 levels in that building chain and the required level of main settlement building is 2.
By comparison a building chain that starts at settlement tier 3 and goes all the way to tier 5 will still provide 3 slots, but they will be for tier 5 units (with the highest building built), since the required main settlement level is 5.

An overview of the provided slots is visible when hovering over the garrison upkeep amount in the settlement panel.
Every unit has a little icon that shows if its free.
Upkeep cost for garrison units can be found in the unit info panel on the left side of the screen.

I have not found a way to add my garrison upkeep as its own factor to regular expenses.
This means that the upkeep cost is not taken into account when calculating the players predicted income and instead deducted per script at end of turn.
To display predicted income and the factor tooltip correctly they are modified via script.
This may lead to unexpected behaviour / consequences, that I am not yet aware of, see known issues below and let me know if you notice any other problems.

A unit's upkeep cost is the faction's average upkeep cost for this unit, since calculating the upkeep for all garrison units is much too performance intensive.
For this all armies of a faction that pay upkeep higher than 0 are taken into account.
If no unit is found, the fallback is to calculate the upkeep cost directly.
This should mostly happen in the early game when there are less units overall, so performance impact is limited.

The upkeep cost for units is not 100% accurate but instead the factions average upkeep cost for this unit.
Not much I can do about it as calculating the upkeep cost for all units would be way too bad for performance.
Workaround - no workaround.

The tooltip for projected income will not be modified if mouseover originates from within the top bar.
Workaround - mouseover the projected income component from empty space below rather than from the side / topbar.

The detailed treasury breakdown does not list the expenses for garrisons at the moment.
Workaround - no workaround, remind me to implement this.

It is impossible to go properly bankrupt just from garrison upkeep.
Since players' treasury can't go below 0, it is possible that the full amount of garrisons costs can't be deducted from the players treasury.
If the actual income is still positive this means that the player will simply be set to 0 and then earn their actual income, thereby avoiding paying (most) of the garrison upkeep.
Workaround - no workaround, I have no idea how to solve this atm.