markdown: bump docker-finance to v1.3.0

01c45cf assets/markdown: plugins: add bitcoin documentation (Aaron Fiore)
06cf912 markdown: plugins: update documentation (Aaron Fiore)
f3952ba markdown: move plugins documentation (Aaron Fiore)

README.md

@@ -18,7 +18,7 @@
 
 <div align="center">
 
-[<img src="assets/branding/png/docker-finance.png" height=75% width=75% align="center" />](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+[<img src="assets/branding/png/docker-finance.png" height=75% width=75% align="center" />](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 </div>
 

markdown/How-do-I-connect.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10% />](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10% />](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I connect?](#how-do-i-connect)**
   * [`#docker-finance:matrix.org`](#docker-financematrixorg)

markdown/How-do-I-contribute.md

@@ -1,7 +1,7 @@
 
 [//]: # (docker-finance | modern accounting for the power-user)
 [//]: # ()
-[//]: # (Copyright [C] 2021-2025 Aaron Fiore [Founder, Evergreen Crypto LLC])
+[//]: # (Copyright [C] 2021-2026 Aaron Fiore [Founder, Evergreen Crypto LLC])
 [//]: # ()
 [//]: # (This program is free software: you can redistribute it and/or modify)
 [//]: # (it under the terms of the GNU General Public License as published by)
@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I contribute?](#how-do-i-contribute)**
   * [Donate](#donate)
@@ -34,7 +34,7 @@ Your input while using docker-finance is [valuable and appreciated](How-do-I-con
 
 #### Dependencies
 
-If you like docker-finance, please consider donating to the [wonderful projects](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.yaml) that it relies upon.
+If you like docker-finance, please consider donating to the [wonderful projects](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.yaml) that it relies upon.
 
 ### Development
 
@@ -47,28 +47,11 @@ When developing with the [`finance` image](What-does-it-do.md#image-finance), yo
   * Developer mockup CSVs can be found in the `mockup` directories within the hledger-flow section of the docker-finance repository
   * Developer mockup CSVs will *intentionally* have multiple years within in a `1-in/year` directory in order to test for year parsing
 
-When developing non-code documentation, please work with the [dfi-docs](https://gitea.com/EvergreenCrypto/dfi-docs) repository.
+When developing non-code documentation, please work with the [dfi-docs](https://gitea.evergreencrypto.co/EvergreenCrypto/dfi-docs) repository.
 
 #### 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).
-
-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).
-
-Upon client `gen`, a client-side directory layout is generated. This layout consists of:
-  - `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker`
-    - Custom plugins that function only client-side (`lib_docker`)
-  - `${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):
-  - 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.com/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) and [`container/plugins`](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/container/plugins)).
-
-For more information, see the example plugins and help usage of each module, e.g.; `plugins help` or `help()`.
-
-> 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`).
+Primary plugin documentation can be found [here](How-do-I-use-it.md#plugins). Technically speaking, you can write custom plugins and never need to merge with the repository but if you feel that the plugin(s) would be beneficial to the public, add testcases and send everything with a [pull request](#pull-request).
 
 #### Pull Request
 
@@ -81,12 +64,171 @@ Before sending a pull request:
    - [Bash](https://google.github.io/styleguide/shellguide.html)
    - [C++](https://google.github.io/styleguide/cppguide.html)
      * Ignore their rule for [no `throw`'ing / no `exceptions`](https://google.github.io/styleguide/cppguide.html#Exceptions)
-   - [PHP](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/PhpCsFixer.rst)
+   - [PHP](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/PSR12.rst)
 4. If you can, please document the code in Doxygen style where applicable and run `doxygen gen` to see your code documentation.
 
-Any non-code documentation should go into the [dfi-docs](https://gitea.com/EvergreenCrypto/dfi-docs) repository.
+Any non-code documentation should go into the [dfi-docs](https://gitea.evergreencrypto.co/EvergreenCrypto/dfi-docs) repository.
 
-#### Notes
+#### CI using self hosted `gitea` with `act_runner`
+
+This documentation is intended for users who are not familiar with Docker, Gitea or its CI process.
+
+🚨 **It's recommended to host these instances LOCALLY within a virtual machine (such as VirtualBox or QEMU)**
+
+##### Minimum host requirements (guest VM)
+
+  - Arch Linux guest VM
+    * ~100 GiB disk space for entire VM
+  - Guest VM packages
+    * `docker` `docker-compose` `docker-buildx`
+    * `npm` (needed for `actions` e.g., `actions/checkout@v4` etc.)
+    * `act_runner`
+    * `vim` (needed for `dfi` client functional tests)
+  - Host/Guest port forwarding (such as VirtualBox NAT Port Forwarding)
+    * 3000 to 3000  (gitea web)
+    * 2345 to 2345  (gitea ssh)
+    * 2222 to 22  (VM/arch ssh)
+    * NOTE: if using VirtualBox, and guest uses DHCP, Guest IP will likely be 10.0.2.15
+
+⚠️ All further documentation will assume the following:
+  - Deployments are entirely within the guest virtual machine (Arch Linux)
+  - For the `gitea` instance: the running user is a privileged non-root user who is a member of the `docker` group
+
+##### Install host (guest VM) packages
+
+   ```bash
+   sudo pacman -Syu --noconfirm docker docker-compose docker-buildx npm vim
+   ```
+
+##### Install `gitea`
+
+1. Easily deploy gitea with a [rootless docker image](https://docs.gitea.com/installation/install-with-docker-rootless) with database (MySQL), and ensure the following in `docker-compose.yml`:
+
+   ```yaml
+       ports:
+         - "3000:3000"
+         - "2345:2345"
+   ```
+
+2. After following Gitea's deployment instructions, in the current gitea directory, bring up the instance (not detached)
+
+   ```bash
+   docker compose up
+   ```
+
+3. Visit `http://127.0.0.1:3000`
+
+   - Change ssh port to 2345 (accept all other defaults)
+   - Optional: for email registration, register a `@localhost.localdomain` user
+
+4. Bring down instance
+
+   Press Ctrl+C if not detached (otherwise, `docker compose down`).
+
+5. Run the following in the current existing gitea directory
+
+   ```bash
+   sed -i 's:SSH_LISTEN_PORT = 2222:SSH_LISTEN_PORT = 2345:' config/app.ini
+   ```
+
+6. Bring instance back up
+
+   ```bash
+   docker compose up -d
+   ```
+
+7. Setup `docker-finance` repository
+
+   - Visit `http://127.0.0.1:3000`, login and create the repository
+   - Push the `master` branch
+
+##### Install `act_runner`
+
+Returning back you the guest VM, run the following:
+
+   ```bash
+   sudo pacman -Syu --noconfirm act_runner \
+     && sudo usermod -aG docker act_runner
+   ```
+
+##### Prepare `act_runner` user
+
+The `act_runner` package will create a system level user with shell `/usr/bin/nologin`. This is a standard security practice and usually should never be touched. However, because we are working entirely within a virutal machine, and we need the runner to run all functional tests as a regular user (a `dfi`-ism; and `act_runner` should not `su` into any other user), the following will be required.
+
+⚠️ **If you're not using a VM (as was recommended at documentation start), now is the time to reconsider**
+
+As root, run the following:
+
+   ```bash
+   chsh -s /usr/bin/bash act_runner \
+     && usermod --expiredate= act_runner \
+     && pushd /var/lib/act_runner \
+     && touch .bashrc \
+     && chown act_runner:act_runner .bashrc \
+     && popd
+   ```
+
+##### Prepare `act_runner` config
+
+The following label must be added to `/etc/act_runner/config.yaml` in order to build locally on the "host" (guest VM).
+
+Optional: you can remove all other ubuntu labels if this is a dedicated instance for docker-finance.
+
+   ```yaml
+     labels:
+   #   - ubuntu labels...
+       - "archlinux_vm:host"
+   ```
+
+##### Register `act_runner`
+
+As root, run the following:
+
+   ```bash
+   pushd /var/lib/act_runner \
+     && act_runner --config /etc/act_runner/config.yaml register \
+     && popd
+   ```
+
+1. Enter `http://127.0.0.1:3000` for instance
+2. Enter token from the "Create new Runner" pull down in your instance's `Settings -> Actions -> Runners` page
+3. Press enter to use default runner name (or make a new name)
+
+Then enable the `act_runner` systemd service:
+
+   ```bash
+   systemctl enable --now act_runner
+   ```
+
+To see if your runner is found and "Idle", login to your gitea instance refresh the "Runners" page.
+
+##### Add Secrets to `gitea` Actions
+
+Various `dfi` APIs will require API keys for successful `fetch`ing.
+
+In Gitea's `Settings -> Actions -> Secrets -> Add Secret`, add the following `Name`/`Value` pairs after visiting their respective websites. Once you obtain your key, simply copy/paste into the respective `Value` fields:
+
+   `Names`:
+
+   - `CI_DFI_FETCH_MOBULA`
+   - `CI_DFI_FETCH_COINGECKO` (this is optional and can be ignored unless you want to use a paid plan)
+   - `CI_DFI_FETCH_ETHERSCAN`
+
+##### Push your changes to `gitea`
+
+And watch the "Actions" page on your Gitea instance do its thing.
+
+##### CI notes
+
+DinD cannot be used because of bind-mounting limitations with DinD. Since the runner's container needs to mount `dfi`'s layout, and `dfi` does not use named volumes, the existing layout must also exist on the host (and intermediate) container with the same ownership as the runner's container user. The maintenance of such a setup is not worth the effort when the above setup can easily be deployed.
+
+See also:
+
+- https://docs.gitea.com/usage/actions/act-runner
+- https://gitea.com/gitea/act_runner/issues/380
+- https://stackoverflow.com/questions/55845723/volume-bind-mounting-from-docker-in-docker
+
+#### Development notes
 
 - Regarding client configuration, Docker volumes aren't used because of chicken-or-the-egg problem (among other reasons). docker-finance needs the client environment *before* building the Docker image and spawning the subsequent container (which would rely on volumes).
 - As described in [Mostly-Unified CLI](How-do-I-use-it.md#mostly-unified-cli), to use a developer version of any `dfi` image, simply build and tag with any tag name you'd like (e.g., `dfi archlinux/${USER}:dev build type=default`)

markdown/How-do-I-get-started.md

@@ -1,7 +1,7 @@
 
 [//]: # (docker-finance | modern accounting for the power-user)
 [//]: # ()
-[//]: # (Copyright [C] 2021-2025 Aaron Fiore [Founder, Evergreen Crypto LLC])
+[//]: # (Copyright [C] 2021-2026 Aaron Fiore [Founder, Evergreen Crypto LLC])
 [//]: # ()
 [//]: # (This program is free software: you can redistribute it and/or modify)
 [//]: # (it under the terms of the GNU General Public License as published by)
@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I get started?](#how-do-i-get-started)**
   * [Installation](#installation)
@@ -31,7 +31,9 @@ To get started, you'll only need a modern Linux client (host) with a working Doc
 
 ### Installation
 
-docker-finance *should* work out-of-the-box on any modern Linux system. For example, if your client (host) is Ubuntu, the default installation of `coreutils`, `shells` and `utils` that came with your system will satisfy requirements. However, you'll still need to manually install Docker (see below).
+`dfi` *should* work out-of-the-box on any modern Linux system. For example, if your client (host) is Ubuntu, the default installation of `coreutils`, `shells` and `utils` that came with your system will satisfy requirements. However, you'll still need to manually install Docker (see below).
+
+> Watch this [example demo](../assets/examples/webm/client-install.webm) for a quick showcase of the below instructions (using a development test profile)
 
 1. Install required dependencies:
 
@@ -53,25 +55,17 @@ docker-finance *should* work out-of-the-box on any modern Linux system. For exam
    - A terminal multiplexer like [tmux](https://github.com/tmux/tmux/wiki) or [screen](https://www.gnu.org/software/screen/)
    - A terminal file manager like [mc](https://midnight-commander.org/) (Midnight Commander)
 
-3. Prepare your repository:
+3. Prepare your base path and repository:
 
-   Before proceeding, change your directory to a *persistent* path that you'll likely keep; as your client (host) shell environment will be aliased/sourced to the path you choose.
+   - Before proceeding, change your directory to a *persistent base path* that you intend to keep; as this will be the default base path for all data going forward
+     * The absolute path of your current working directory + `./docker-finance` will be the default base path to house all data
+     * If you'd like, you *can* change the base path later during [Client Generation](#client-generation)
 
      ```bash
+     # NOTE: you can change the domain to `gitea.com`, as this repository is also mirrored there
      if hash git &>/dev/null; then
-       if [ -d docker-finance ]; then
-         if pushd docker-finance &>/dev/null; then
-           if ! git pull --tags; then
-             echo "FATAL: docker-finance repo not pulled" >&2
-           fi
-           popd 1>/dev/null
-         else
-           echo "FATAL: docker-finance repo not found" >&2
-         fi
-       else
-         if ! git clone https://gitea.com/EvergreenCrypto/docker-finance; then
+       if ! git clone --depth=1 https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance docker-finance/repo -b v1.3.0; then
            echo "FATAL: docker-finance repo not cloned" >&2
-         fi
        fi
      else
        echo "FATAL: git not found" >&2
@@ -80,7 +74,7 @@ docker-finance *should* work out-of-the-box on any modern Linux system. For exam
 
 4. Verify your repository (recommended):
      ```bash
-     if pushd docker-finance/ 1>/dev/null; then
+     if pushd docker-finance/repo 1>/dev/null; then
        gpg --keyserver hkp://keyserver.ubuntu.com --recv-key 518A22F85BEFD32BCC99C48603F90C4F35E0213E \
          && git verify-commit $(git log -n1 --pretty=format:"%H") \
          && echo -e "\nSUCCESS: now confirm matching key = 518A22F85BEFD32BCC99C48603F90C4F35E0213E" \
@@ -91,10 +85,10 @@ docker-finance *should* work out-of-the-box on any modern Linux system. For exam
 
 5. Prepare your client (host) shell environment:
 
-   Install convenience aliases and command completion to your shell environment (see [install.bash](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/install.bash) for details):
+   Install convenience aliases and command completion to your shell environment (see [install.bash](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/install.bash) for details):
 
      ```bash
-     ./docker-finance/client/install.bash && source ~/.bashrc
+     ./docker-finance/repo/client/install.bash && source ~/.bashrc
      ```
    > - The `dfi` alias of `docker-finance` is the recommended alias to use for for all client/container operations
    > - After your first image is built (step 7), you can use commandline completion for all `dfi` images and commands
@@ -221,7 +215,7 @@ The client (host) configuration file:
   - client/container configurations can be stored on shared NFS/CIFS or related network storage (with applicable user permissions)
     - allows for customizable locations of *all* container data on any mountable filesystem (as a replacement for Docker Volumes)
   - consists solely of variables in the format `DOCKER_FINANCE_VARIABLE=value` and is used by both Docker and docker-finance
-  - default template variables can be found in [gen.bash](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/client/env/gen.bash), as described below
+  - default template variables can be found in [gen.bash](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/conf.d/client/env/gen.bash), as described below
 
 After `gen` is complete, you can edit this file with the client (host) command: `edit type=env` (see [Client (Host) Command Format](How-do-I-use-it.md#client-host-command-format)).
 
@@ -230,14 +224,14 @@ After `gen` is complete, you can edit this file with the client (host) command:
 
 Client (host) configuration path. Parent directory for client configuration files.
 
-- Example: `DOCKER_FINANCE_CLIENT_CONF=/home/${USER}/.config/docker-finance.d`
+- Example: `DOCKER_FINANCE_CLIENT_CONF=/home/${USER}/docker-finance/conf.d`
 
 
 > DOCKER_FINANCE_CLIENT_FLOW
 
-Client (host) finance-flow path. Parent directory for all profiles and end-user data.
+Client (host) workflow path. Parent directory for all profiles and end-user data.
 
-- Example: `DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/finance-flow`
+- Example: `DOCKER_FINANCE_CLIENT_FLOW=/net/nfs4/docker-finance/flow`
 
 
 > DOCKER_FINANCE_CLIENT_REPO
@@ -246,7 +240,7 @@ Client (host) path for the docker-finance code repository (from the host's persp
 
 This parent directory is where the `client` and `container` directories are located.
 
-- Example: `DOCKER_FINANCE_CLIENT_REPO=/net/nfs4/git/docker-finance`
+- Example: `DOCKER_FINANCE_CLIENT_REPO=/net/nfs4/git/docker-finance/repo`
 
 
 > DOCKER_FINANCE_CLIENT_SHARED
@@ -255,7 +249,7 @@ Client (host) path for the client/container shared directory.
 
 The bind-mount is used exclusively for non-essential file sharing (custom scripts or any file you wish).
 
-- Example: `DOCKER_FINANCE_CLIENT_SHARED=/mnt/share.d`
+- Example: `DOCKER_FINANCE_CLIENT_SHARED=/mnt/docker-finance/share.d`
 
 
 > DOCKER_FINANCE_CLIENT_PLUGINS
@@ -264,7 +258,7 @@ Client (host) path for the client/container shared *custom* plugins.
 
 The bind-mount is used exclusively for user-added plugins not in the repository.
 
-- Example: `DOCKER_FINANCE_CLIENT_PLUGINS=/home/${USER}/Development/dfi_custom-plugins`
+- Example: `DOCKER_FINANCE_CLIENT_PLUGINS=/home/${USER}/Development/docker-finance/custom-plugins`
 
 
 > DOCKER_FINANCE_CONTAINER_CMD
@@ -280,7 +274,7 @@ Default: `finance.bash` (internally aliased to `finance` and `dfi`)
 
 The container's configuration path (bind-mounted to client's (host's) configuration path).
 
-- Example: `DOCKER_FINANCE_CONTAINER_CONF=/home/${USER}/.config/docker-finance.d`
+- Example: `DOCKER_FINANCE_CONTAINER_CONF=/home/${USER}/docker-finance/conf.d`
 
 
 > DOCKER_FINANCE_CONTAINER_EDITOR
@@ -292,11 +286,11 @@ The container's default text editor.
 
 > DOCKER_FINANCE_CONTAINER_FLOW
 
-The container's finance-flow path from the container's perspective.
+The container's workflow path from the container's perspective.
 
-This path is bind-mounted to the client's (host's) finance-flow path.
+This path is bind-mounted to the client's (host's) flow path.
 
-- Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/finance-flow`
+- Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/docker-finance/flow`
 
 
 > DOCKER_FINANCE_CONTAINER_REPO
@@ -305,14 +299,14 @@ The container's docker-finance code repository path (as viewed from the containe
 
 This path is bind-mounted to the client's (host's) `docker-finance/container` path.
 
-- Example: `DOCKER_FINANCE_CONTAINER_REPO=/home/${USER}/docker-finance`
+- Example: `DOCKER_FINANCE_CONTAINER_REPO=/home/${USER}/docker-finance/repo`
 
 
 > DOCKER_FINANCE_CONTAINER_SHARED
 
 The container's `share.d` path, bind-mounted to client's (host's) `share.d` path.
 
-- Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/share.d`
+- Example: `DOCKER_FINANCE_CONTAINER_FLOW=/home/${USER}/docker-finance/share.d`
 
 
 > DOCKER_FINANCE_CONTAINER_PLUGINS
@@ -321,7 +315,7 @@ The client's custom plugin path (as viewed from the container).
 
 This path is bind-mounted to the client's (host's) `${DOCKER_FINANCE_CLIENT_PLUGINS}/container` path.
 
-- Example: `DOCKER_FINANCE_CONTAINER_PLUGINS=/home/${USER}/plugins`
+- Example: `DOCKER_FINANCE_CONTAINER_PLUGINS=/home/${USER}/docker-finance/plugins`
 
 
 > DOCKER_FINANCE_CPUS
@@ -393,7 +387,7 @@ The client (host) custom Dockerfile:
     - allows you to append any Dockerfile command to a generated build
   - is located in the `${DOCKER_FINANCE_CLIENT_CONF}/client/Dockerfiles/` directory
     - format consists of `username@hostname` where `username` is your host username and `hostname` is your machine's hostname
-  - default generated templates can be found [here](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/client/Dockerfiles)
+  - default generated templates can be found [here](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/conf.d/client/Dockerfiles)
 
 After `gen` is complete, you can edit this file with the client (host) command: `edit type=build` (see [Client (Host) Command Format](How-do-I-use-it.md#client-host-command-format)).
 
@@ -409,7 +403,7 @@ The client/container shell script (Superscript) is a bind-mounted (by directory)
 
 See the in-file comments for further documentation:
 
-  - [superscript.bash.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/shell/superscript.bash.in)
+  - [superscript.bash.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/conf.d/container/shell/superscript.bash.in)
 
 After `gen` is complete, you can edit this file with the client (host) command: `edit type=shell` (see [Client (Host) Command Format](How-do-I-use-it.md#client-host-command-format)).
 
@@ -427,7 +421,7 @@ By default, this file will contain user aliases for all container commands. Thes
 
 See the in-file comments for further documentation:
 
-  - [subscript.bash.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/shell/subscript.bash.in)
+  - [subscript.bash.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/conf.d/container/shell/subscript.bash.in)
 
 After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=shell` (see [Container Command Format](How-do-I-use-it.md#container-command-format)).
 
@@ -437,7 +431,7 @@ The source of all remote API fetching configurations (exchanges, blockchains, ma
 
 See the in-file comments for further documentation:
 
-  - [fetch.yaml.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/fetch/fetch.yaml.in)
+  - [fetch.yaml.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/conf.d/container/fetch/fetch.yaml.in)
 
 After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=fetch` (see [Container Command Format](How-do-I-use-it.md#container-command-format)).
 
@@ -447,7 +441,7 @@ The source of all custom metadata information (typically used to store cryptocur
 
 See the in-file comments for further documentation:
 
-  - [meta.csv.in](https://gitea.com/EvergreenCrypto/docker-finance/src/branch/master/client/docker-finance.d/container/meta/meta.csv.in)
+  - [meta.csv.in](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/conf.d/container/meta/meta.csv.in)
 
 After `gen` is complete, from within the container, you can edit this file with: `dfi profile/subprofile edit type=meta` (see [Container Command Format](How-do-I-use-it.md#container-command-format)).
 

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

@@ -1,7 +1,7 @@
 
 [//]: # (docker-finance | modern accounting for the power-user)
 [//]: # ()
-[//]: # (Copyright [C] 2021-2025 Aaron Fiore [Founder, Evergreen Crypto LLC])
+[//]: # (Copyright [C] 2021-2026 Aaron Fiore [Founder, Evergreen Crypto LLC])
 [//]: # ()
 [//]: # (This program is free software: you can redistribute it and/or modify)
 [//]: # (it under the terms of the GNU General Public License as published by)
@@ -16,11 +16,12 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[How do I use it?](#how-do-i-use-it)**
   * [Mostly-Unified CLI](#mostly-unified-cli)
   * [Flow Layout](#flow-layout)
+  * [Plugins](#plugins)
   * [Caveats & Oddities](#caveats--oddities)
 
 ## How do I use it?
@@ -141,7 +142,7 @@ Peeking inside `${DOCKER_FINANCE_CONTAINER_FLOW}/profiles/profile/subprofile`, y
 - `all-years.journal` and `directives.journal`
   - These top-level journals are generated by `hledger-flow`. Ignore these and use the container `edit` command for all journal editing.
 
-- `docker-finance.d`
+- `conf.d`
   - Location of all docker-finance configuration files (see `edit help` for details).
 
 - `import`
@@ -167,17 +168,165 @@ All `times` related files will reside in `${DOCKER_FINANCE_CONTAINER_FLOW}/times
 
 See the container `times help` command for details.
 
+### Plugins
+
+Plugins (pluggables) allow you to leverage `dfi` client/container APIs, libraries and environments to meet your unique needs.
+
+Checkout this two-part client/container set of [Bitcoin plugins](#plugins-bitcoin) to see how all APIs/libraries/environments can work together in unison.
+
+For more information and other examples, see some of the various existing plugins (pluggables) and respective help usage, i.e.;
+
+  - Client-side (host): `dfi <platform/user:tag> plugins help`
+  - Container-side: `dfi <profile/subprofile> plugins help`
+  - Within `root` interpreter: `dfi::help()`
+
+#### Plugins: Layout
+
+Plugins are categorical:
+
+  1. Repository (`repo`) plugins
+     - These plugins remain within the repository and will require a pull request for any changes to be made to them.
+
+  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`
+
+#### Plugins: Bitcoin
+
+`dfi`'s bitcoin plugin is a two-part client/container set of plugins that gives you direct access to bitcoin's libbitcoinkernel (and related headers/symbols).
+
+The following demo assumes that you'll be using a fresh setup and that you've at least satisfied the required dependencies in [Installation](How-do-I-get-started.md#installation) (Docker Engine/Compose/Buildx, Bash, Git).
+
+If you're a first-time user and/or developer who simply wants a quickstart, run the following before proceeding:
+
+```bash
+git clone --depth=1 https://gitea.com/EvergreenCrypto/docker-finance docker-finance/repo
+./docker-finance/repo/client/install.bash && source ~/.bashrc
+dfi archlinux/${USER}:default gen all=all profile=testprofile/testuser confirm=no dev=on
+```
+
+##### Plugins: Bitcoin: Client
+
+Here, we prepare client-side dependencies and build everything needed for the container-side plugin:
+
+<video src="../assets/examples/webm/client-plugins-bitcoin.webm" controls></video>
+
+Shell 1:
+
+```bash
+# NOTE: editing will only be required once (unless you `gen type=build` in the future)
+dfi archlinux/${USER}:default edit type=build
+dfi archlinux/${USER}:default build type=default
+```
+
+Shell 2:
+
+```bash
+dfi archlinux/${USER}:default up
+```
+
+Shell 1:
+
+```bash
+dfi archlinux/${USER}:default plugins repo/bitcoin.bash get
+dfi archlinux/${USER}:default plugins repo/bitcoin.bash build
+```
+
+##### Plugins: Bitcoin: Container
+
+Here, we see the multiple ways the container-side plugin can be loaded and also test its functionality:
+
+<video src="../assets/examples/webm/container-root-plugins-bitcoin_cli.webm" controls></video>
+
+Shell 2 (or open a new shell into container, as seen in the demo):
+
+```bash
+dfi testprofile/testuser root
+```
+
+Within `root` interpreter:
+
+```cpp
+// NOTE:
+//   - The demo shows `btck` tab completion (which can't be put here)
+//   - semicolons are not needed, since the following is executed per line
+GetRandHash()
+dfi::plugin::load("repo/bitcoin/bitcoin.cc")
+GetRandHash()
+dfi::macro::load("repo/test/unit.C", "Random*")
+.quit
+```
+
+Shell 2:
+
+```bash
+BENCHMARK_FILTER="^Random" dfi testprofile/testuser root plugins/repo/bitcoin/bitcoin.cc 'dfi::macro::load(\"repo/test/benchmark.C\"); dfi::common::exit(0);'
+dfi testprofile/testuser root plugins/repo/bitcoin/bitcoin.cc 'dfi::macro::load(\"repo/web/server.C\")'
+```
+
+##### Plugins: Bitcoin: Web browser
+
+Here, we see a real-world visualization of what the container-side plugin can produce. In this example, with the plugin previously loaded (as seen above), we sample bitcoin's RNG:
+
+<video src="../assets/examples/webm/container-root-plugins-bitcoin_web.webm" controls></video>
+
+- Open browser to `http://127.0.0.1:8080`
+  * Default port can be changed with client-side command: `dfi archlinux/${USER}:default edit type=env`
+- Click `rng_sample` -> Enter sample amount
+- Click `reload`
+
 ### Caveats & Oddities
 
-#### Flow Layout
+#### Caveats & Oddities: Flow
 
-Your `finance-flow` directory will contain a symlink called `src` which links to code that processes your data. **Do not delete this symlink**.
+Your `flow` directory will contain a symlink called `src` which links to code that processes your data. **Do not delete this symlink**.
 
-##### *Prices*
+##### Caveats & Oddities: Flow: Prices
 
 Before you try to infer market prices, be sure to fetch prices *before* you do your first import (or first import of the year). If you do not fetch, the prices journal will **not** be included within the import and, if you have a previous year of prices, **you will unwittingly infer against that previous year instead of your expected year!**
 
-##### *Accounts: Trezor*
+##### Caveats & Oddities: Flow: Accounts: Trezor
 
 In the "Trezor Suite" app, change your wallet name to your subaccount(s). For example, to delineate between your Trezor One from several Trezor T devices, and to delineate between their separate wallets *within* every device, follow these steps:
 
@@ -194,7 +343,7 @@ docker-finance relies on `Amount unit` within the file for the actual symbol/cur
   1. This allows you to maintain device continuity by reusing wallet names for different currencies.
   2. This allows you to export, in the future, to the correct file from the associated hardware wallet because each hardware wallet exports its own unique CSV.
 
-#### Taxes
+##### Caveats & Oddities: Flow: Taxes
 
 - If you have a wallets designated for `SPEND`ing/`GIFT`ing or `INCOME`, you can use custom rules to mark all outgoing/incoming transactions as such (ex., using tags `taxed_as:SPEND`/`taxed_as:GIFT`/`taxed_as:INCOME`/etc.). See implementation for details.
 - **WARNING**: *all* `GIFTIN` cost-basis must be manually entered from the corresponding `GIFT` results/calculations (as gifted from another).

markdown/What-does-it-do.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[What does it do?](#what-does-it-do)**
   * [Highlights](#highlights)

markdown/What-is-supported.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[What is supported?](#what-is-supported)**
   * [CeFi (centralized custodians)](#cefi)

markdown/Where-is-the-legalese.md

@@ -16,7 +16,7 @@
 [//]: # (You should have received a copy of the GNU General Public License)
 [//]: # (along with this program. If not, see <https://www.gnu.org/licenses/>.)
 
-# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.com/EvergreenCrypto/docker-finance "docker-finance")
+# [<img src="../assets/branding/png/dfi.png" height=10% width=10%/>](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance "docker-finance")
 
 - **[Where is the legalese?](#where-is-the-legalese)**
   * [License and Disclaimer](#license-and-disclaimer)