markdown: plugins: update documentation

markdown/How-do-I-use-it.md

@@ -170,24 +170,65 @@ See the container `times help` command for details.
 
 ### Plugins
 
-Plugins allow you to use docker-finance public APIs, libraries and environment (client and/or container) to meet your unique needs. These plugins are categorical; as in, there are client-side ("custom") plugins and repository ("repo") plugins. Additionally, there are subcategories such as `docker`, `finance` and `root` (respective to their modules).
+Plugins (pluggables) allow you to leverage `dfi` client/container APIs, libraries and environments to meet your unique needs.
 
-Client-side custom plugins allow you to drop-in any code that you write and keep them locally. Repository plugins are plugins that remain within the repository and will require a pull request for any changes to be made. Client-side custom plugins can be used for either client or container modules (see directory layout).
+For more information and examples, see some of the various existing plugins (pluggables) and respective help usage, i.e.;
 
-Upon client `gen`, a client-side directory layout is generated. This layout consists of:
+  - Client-side (host): `dfi <platform/user:tag> plugins help`
-  - `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker`
+  - Container-side: `dfi <profile/subprofile> plugins help`
-    - Custom plugins that function only client-side (`lib_docker`)
+  - Within `root` interpreter: `dfi::help()`
-  - `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/{finance,root}`
-    - Custom plugins that function only container-side (`lib_finance`, `root`)
 
-**WARNING: don't change the parent client-side directory layout** (although, you can add subdirectories):
+#### Plugins: Layout
-  - e.g., `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/finance/my_experimental_plugins/{file1.ext,file2.ext}`
 
-This client-side "custom" layout somewhat mirrors the repository's plugins layout (see [`client/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) and [`container/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/container/plugins)).
+Plugins are categorical:
 
-For more information, see the example plugins and help usage of each module, e.g.; `plugins help` or `help()`.
+  1. Repository (`repo`) plugins
+     - These plugins remain within the repository and will require a pull request for any changes to be made to them.
 
-> Note: for custom plugins within directory `docker` and `finance` that utilize the shell, any language can be used so long as the file is executable, reads the shell environment and can initiailize their respective libraries (`lib_docker`, `lib_finance`).
+  2. End-user (`custom`) plugins
+     - These plugins remain on your client (host) and are bind-mounted to your container; allowing you to drop-in any code that you write while keeping them local and private.
+
+Within these categories are subcategories where plugins exist either client-side (host) or container-side; meaning, they rely upon (or operate within) their respective client/container APIs/libraries/environments:
+
+  1. `client` | *Tends to operate only client-side (host) but can also utilize a container*
+     - `docker` | *Operates **only** from the `bash` shell*
+       * Called client-side with `dfi <platform/user:tag> plugins`
+       * Can be any language so long as:
+         - The file is executable by the shell
+         - The plugin reads the shell environment
+         - The plugin initializes the respective library (`lib_docker`)
+  2. `container` | *Operates **only** within the container*
+     - `finance` | *Operates **only** from the `bash` shell*
+       * Called container-side with `dfi <profile/subprofile> plugins`
+       * Can be any language so long as:
+         - The file is executable by the shell
+         - The plugin reads the shell environment
+         - The plugin initializes the respective library (`lib_finance`)
+     - `root` | *Operates **only** within the `root` interpreter*
+       * Called container-side by either two different ways:
+         - Within a running `dfi <profile/subprofile> root` instance:
+           * `dfi::plugin::load("repo/a_repo_plugin/plugin.cc")`
+           * `dfi::plugin::load("custom/my_custom_plugin/plugin.cc")`
+         - With the `dfi <profile/subprofile> root plugins` command
+           * Use tab completion to see available plugins (pluggables)
+       * Can only be languages supported by the interpreter (C/C++)
+
+To mirror these categories, a client-side `custom` plugin directory layout is generated upon `dfi <platform/user:tag> gen`. This layout consists of:
+
+  1. `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker`
+     - This path remains client-side only (not bind-mounted)
+     - This layout mirrors `repo` plugins [`client/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/plugins)
+  2. `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/{finance,root}`
+     - The container directory is bind-mounted to `DOCKER_FINANCE_CONTAINER_PLUGINS`
+     - This layout mirrors `repo` plugins [`container/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/container/plugins)
+
+**WARNING: don't change the above expected layout!** However, you can add subdirectories, e.g.;
+
+  - `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker/my_docker_plugins/plugin.bash`
+  - `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/finance/my_finance_plugins/plugin.bash`
+  - `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/root/my_plugin/my_plugin.cc`
+    * NOTE: `root` pluggable auto-(un)loading requires a parent directory as the callable namespace (and more)
+      - See docs for details: `dfi dev-tools/${USER}:default doxygen gen`
 
 ### Caveats & Oddities