In this particular instance, I'm trying to pre-install libraries into a docker image... an image where a users home-directory is then volume-mounted by the image at run-time.

The FAQ says:

Extensions are stored in ~/.local/share/code-server/extensions by default.

On Linux and macOS if you set the XDG_DATA_HOME environment variable, the extensions directory will be $XDG_DATA_HOME/code-server/extensions. In general, we try to follow the XDG directory spec

The downside to a single directory is that one cannot have pre-installed extensions baked into the image and allow the user to persistently install their own extensions.

Reading the spec (https://specifications.freedesktop.org/basedir-spec/latest/), it talks about $XDG_DATA_DIRS, so I should be able to do something like:

FROM someBaseImage

RUN do_magick_to_install_code-server

ENV XDG_DATA_DIRS="<xdg_data_home_path>:/usr/share/code-server"
RUN mkdir -p /usr/share/code-server/extensions
COPY my-local/configuration/extensions /usr/share/code-server/extensions

RUN do_more_clever_stuff

I can build an image, and that image will have valid files under /usr/share/code-server/extensions, however the code-server doesn't list them as installed packages.

.. The my-local/configuration/extensions directory contains an extensions.json file, and three directories: mikoz.black-py-1.0.3-universal, ms-python.debugpy-2025.0.1-linux-x64, and ms-python.python-2025.0.0-universal

..... and yes, if I install images in a running docker image, they get installed in ~/.local/share/code-server/extensions - which is fine, and gives persistent user configuration..... but does not provide any pre-configuration

Am I miss-understanding XDG?
Am I using XDG incorrectly?
Am I on a hiding to nothing?