best way to mixin e.g. custom plan files with existing TKL images?

If you are adding these custom packages to multiple builds, the best place to put them is in common (by default /turnkey/fab/common). In there you'll find the base plan. That is applied to all servers (it's essentially Core's plan).

Alternatively, if you don't want to do that, you could create your own custom plan (i'd recommend putting it in the turnkey directory, e.g. common/plans/turnkey/custom. Then in each appliance that wants this plan included, add it near the top of the plan file (e.g. products/core/plan/main - just below '#include '):

#include <turnkey/custom>

if you want other common customisations, you can add them to common too. Including common custom conf scripts and/or overlays is similar (but slightly different). If you want them to be included in all builds, then you can simply add new conf script(s) and/or overlays to common/conf/turnkey.d and/or common/overlays/turnkey.d. Overlays and conf scripts in those locations will be included in all future builds.

Alternatively, if you don't necessarily want them in all builds, but more than one, then you can put them in the directory above those (i.e. common/conf/ and/or common/overlays/ respectively). Then you can include them via each appliance's Makefile. Add them at the top, like this:

COMMON_OVERLAYS = custom-overlay
COMMON_CONF = custom-conf

These will use conf/overlay from common/conf/custom-conf & common/overlays/custom-overlay/ respectively. Additional items can be added on the end (i.e. space separated list).

To make managing a group of conf script(s) and overlays(s) easier, you can group then together via a common makefile (in common/mk/turnkey/). E.g. common/mk/turnkey/custom.mk:

COMMON_OVERLAYS += custom-overlay
COMMON_CONF += custom-conf1 custom-conf2

include $(FAB_PATH)/common/mk/turnkey/custom2.mk
include $(FAB_PATH)/common/mk/turnkey/custom3.mk

Omit lines that aren't relevant (i.e. in my example I'm including other common makefiles, which is likely not relevant to you).

Then to use the common makefile, add this to each server Makefile:

include $(FAB_PATH)/common/mk/turnkey/custom.mk

Hopefully that all makes sense and answers your question properly.

That's a great suggestion. So I've just opened a pull request including a (lightly edited) copy/paste of my earlier post. When I was doing that I discovered another doc I had previously written but not yet included (not sure why, but it's in there now).

You can see the 2 new pages on GitHub. If you want to read through them pretty rendered, then have a look at the individual files: add-customizations-multiple-apps.rst (the copy/paste of my previous post) and appliance-buildcode-dir.rst (an overview of appliance build code directory contents) files in GitHub.

This is incredibly helpful, thank you.

At some point I'm hoping I'll have gone through all this enough to be able to contribute to the docs, but the above could honestly be repackaged as-is as a concise documentation item on "how do I add customizations to some/all of the images I generate with TKLdev?" and help anybody who's gotten to the point of churning out their own fresh images :)