docs(programs): update programs api dev docs (#280)

and programs bootstrap file

Author: wpbonelli

docs/md/dev/programs.md

@@ -530,34 +530,86 @@ installed = list_installed()
 
 ### Source program integration
 
-For program repositories to integrate:
-
-1. **Generate registry metadata**:
-   ```bash
-   # In program repository
-   python -m modflow_devtools.make_program_registry \
-     --version 6.6.3 \
-     --platforms linux mac win64 \
-     --output .registry/registry.toml
-   ```
-
-2. **Publish registry**: Attach `registry.toml` as a release asset
-
-3. **Example CI integration** (GitHub Actions):
-   ```yaml
-   - name: Generate program registry
-     run: |
-       python -m modflow_devtools.make_program_registry \
-         --version ${{ github.ref_name }} \
-         --platforms linux mac win64 \
-         --output registry.toml
-
-   - name: Upload registry to release
-     uses: actions/upload-release-asset@v1
-     with:
-       asset_path: registry.toml
-       asset_name: registry.toml
-   ```
+For program repositories to integrate, they can generate registry files in two ways:
+
+#### Mode 1: Local Assets (CI/Build Pipeline)
+
+Use this mode when you have local distribution files during CI builds:
+
+```bash
+# Generate registry from local distribution files
+python -m modflow_devtools.programs.make_registry \
+  --dists *.zip \
+  --programs mf6 zbud6 libmf6 mf5to6 \
+  --version 6.6.3 \
+  --repo MODFLOW-ORG/modflow6 \
+  --compute-hashes \
+  --output programs.toml
+```
+
+**How it works:**
+- Uses `--dists` to specify a glob pattern for local distribution files (e.g., `*.zip`)
+- Scans the local filesystem for matching files
+- Requires `--version` and `--repo` arguments
+- Optionally computes SHA256 hashes from local files with `--compute-hashes`
+- Creates asset entries from local file names
+- Auto-detects platform from file names (linux, mac, win64, etc.)
+
+**Example CI integration** (GitHub Actions):
+```yaml
+- name: Generate program registry
+  run: |
+    python -m modflow_devtools.programs.make_registry \
+      --dists *.zip \
+      --programs mf6 zbud6 libmf6 mf5to6 \
+      --version ${{ github.ref_name }} \
+      --repo ${{ github.repository }} \
+      --compute-hashes \
+      --output programs.toml
+
+- name: Upload registry to release
+  uses: softprops/action-gh-release@v1
+  with:
+    files: programs.toml
+```
+
+#### Mode 2: GitHub Release (Testing/Regeneration)
+
+Use this mode to generate a registry from an existing GitHub release:
+
+```bash
+# Generate registry from existing GitHub release
+python -m modflow_devtools.programs.make_registry \
+  --repo MODFLOW-ORG/modflow6 \
+  --version 6.6.3 \
+  --programs mf6 zbud6 libmf6 mf5to6 \
+  --output programs.toml
+```
+
+**How it works:**
+- Fetches release assets from GitHub API using repo and version (tag)
+- Downloads assets if `--compute-hashes` is specified
+- Useful for testing or regenerating a registry for an existing release
+- No `--dists` argument needed - pulls from GitHub directly
+
+**Additional options:**
+```bash
+# With custom executable paths (if not bin/{program})
+python -m modflow_devtools.programs.make_registry \
+  --dists *.zip \
+  --programs mf6:bin/mf6 zbud6:bin/zbud6 custom:path/to/exe \
+  --version 6.6.3 \
+  --repo MODFLOW-ORG/modflow6
+
+# With description and license metadata
+python -m modflow_devtools.programs.make_registry \
+  --dists *.zip \
+  --programs mf6 \
+  --version 6.6.3 \
+  --repo MODFLOW-ORG/modflow6 \
+  --description "MODFLOW 6 groundwater flow model" \
+  --license "CC0-1.0"
+```
 
 ### Program addressing
 

modflow_devtools/programs/programs.toml

@@ -1,63 +1,46 @@
-# Programs API Bootstrap Configuration
-#
 # This file tells modflow-devtools where to find program registries.
-# Programs are discovered from GitHub release assets.
+# Programs are discovered from GitHub release assets (programs.toml)
+# published alongside platform-specific distributions.
 #
-# Each source provides one or more programs (e.g., modflow6 provides mf6, zbud6, libmf6).
-# Program names are globally unique across all sources.
+# Each source provides one or more programs (e.g., modflow6 provides
+# mf6, zbud6, libmf6) as specified in the source's registry file.
 
 [sources.modflow6]
 repo = "MODFLOW-USGS/modflow6"
 refs = ["6.7.0", "6.6.3"]
-# Provides: mf6, zbud6, mf5to6, libmf6
 
 [sources.gridgen]
 repo = "MODFLOW-ORG/gridgen"
 refs = ["v1.0.02"]
-# Provides: gridgen
 
 [sources.triangle]
 repo = "MODFLOW-ORG/triangle"
 refs = ["v1.6"]
-# Provides: triangle
-
-[sources.mfusg]
-repo = "MODFLOW-ORG/mfusg"
-refs = ["v1.5.00"]
-# Provides: mfusg
-
-[sources.mfusgt]
-repo = "MODFLOW-ORG/mfusgt"
-refs = ["v2.6.0"]
-# Provides: mfusg_gsi
-
-[sources.modpath-v7]
-repo = "MODFLOW-ORG/modpath-v7"
-refs = ["7.2.001"]
-# Provides: mp7
-
-[sources.mt3d-usgs]
-repo = "MODFLOW-ORG/mt3d-usgs"
-refs = ["v1.0.0"]
-# Provides: mt3dusgs
-
-[sources.mt3dms]
-repo = "MODFLOW-ORG/mt3dms"
-refs = ["2.0"]
-# Provides: mt3dms
 
 [sources.zonbud]
 repo = "MODFLOW-ORG/zonbud"
 refs = ["v3.01"]
-# Provides: zonbud
 
 [sources.zonbudusg]
 repo = "MODFLOW-ORG/zonbudusg"
 refs = ["v1.01"]
-# Provides: zonbudusg
 
-[sources.executables]
-repo = "MODFLOW-ORG/executables"
-refs = ["latest"]
-# Consolidated repo for legacy programs
-# Provides: mf2005, mf2000, mfnwt, etc.
+[sources.vs2dt]
+repo = "MODFLOW-ORG/vs2dt"
+refs = ["v3.3"]
+
+[sources.mfnwt]
+repo = "MODFLOW-ORG/mfnwt"
+refs = ["v1.3.0"]
+
+[sources.mflgr]
+repo = "MODFLOW-ORG/mflgr"
+refs = ["v2.0.0"]
+
+[sources.mf2000]
+repo = "MODFLOW-ORG/mf2000"
+refs = ["v1.19.01"]
+
+[sources.swtv4]
+repo = "MODFLOW-ORG/swtv4"
+refs = ["v4.00.05"]