Refactor: Complete Postman YAML v3 migration cleanup

- Remove legacy JSON-only Postman tooling and scripts
- Replace visualizer sync tool to operate on request YAML files
- Update release workflow to sync CMTS collection from YAML folder
- Rewrite import/user/tool docs for local-mode YAML source of truth
- Add explicit Postman Desktop v12+ requirement in setup docs
- Update install script command examples to YAML-based workflow
- Remove remaining JSON collection references from repo guidance
- Validate with sync checks, mkdocs strict build, and pytest suite - 2026-03-06 14:45:58

Author: mgarcia01752

README.md

@@ -7,16 +7,16 @@
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0A66C2)](https://pypnmapps.github.io/Postman-PyPNMApps-API/)
 
-This repository contains Postman collections, environment/globals files, and example visualizers for PyPNM API workflows.
+This repository contains Postman local-mode YAML collections, environment/globals files, and example visualizers for PyPNM API workflows.
 
 It includes:
-- Postman collections (`PyPNM`, `PyPNM-CMTS`)
-- environment and globals exports
+- Postman collections (`PyPNM`, `PyPNM-CMTS`) as split YAML request files
+- environment and globals YAML files
 - `visual/` example Postman Visualizer HTML + JSON fixtures
 
 ## Basic Setup
 
-1. Install Postman Desktop (Ubuntu/Windows): `docs/postman-install.md`
+1. Install Postman Desktop v12+ (Ubuntu/Windows): `docs/postman-install.md`
 2. Clone this repository:
 
 ```bash

docs/docs-index.md

@@ -6,7 +6,7 @@ This directory contains user documentation for working with the Postman PyPNMApp
 
 - `docs/postman-install.md` - Postman Desktop download/install steps for Ubuntu and Windows.
 - `docs/postman-import-and-navigation.md` - Import Postman files, configure globals, and navigate collections.
-- `docs/postman-collection-format.md` - Format Postman collection JSON consistently on Windows/Linux.
+- `docs/postman-collection-format.md` - Postman local YAML conventions and migration notes.
 - `docs/user-guide.md` - End-user setup and Postman import/use instructions.
 - `docs/tools.md` - Local developer tooling (`sanitize`, `bump_version`, `release`, `git-save`, `git-push`).
 - `docs/visual-workflow.md` - Simple workflow for editing visuals and syncing Postman visualizer scripts.

docs/postman-collection-format.md

@@ -1,106 +1,40 @@
-# Postman Collection Formatting
+# Postman Local YAML Format
 
-Use the Postman collection formatter to normalize `postman/collections/PyPNM.postman_collection.json` across Linux and Windows.
+This repository uses Postman local-mode YAML artifacts as the source of truth.
 
-It provides:
+## Paths
 
-- consistent JSON formatting (default: 2-space indent)
-- LF line endings (`\n`)
-- schema version detection (`v2.0` / `v2.1`)
-- normalization of non-finite numeric values (`NaN` / `Infinity`) to `null` for valid JSON output
+- Collections: `postman/collections/<collection>/.../*.request.yaml`
+- Environments: `postman/environments/*.environment.yaml`
+- Globals: `postman/globals/*.globals.yaml`
 
-## Setup
+## Required Conventions
 
-Create and activate the repo virtual environment:
+- Keep one request per file (`*.request.yaml`).
+- Preserve folder hierarchy under each collection directory.
+- Keep request `name` human-friendly; keep filename filesystem-safe.
+- Keep Postman variables as literal `{{var}}`.
+- Use quoted strings when needed to avoid YAML type coercion.
+- Prefer multiline block style for long scripts/bodies.
 
-```bash
-./install.sh
-source .venv/bin/activate
-```
-
-If you want Linux/macOS command examples from the installer output, use:
-
-```bash
-./install.sh --os-linux
-```
-
-## Windows (PowerShell) - Default
-
-Formatter wrapper:
-
-- `tools/postman/format_collection.ps1`
-
-Check formatting only:
-
-```powershell
-.\tools\postman\format_collection.ps1 -Check
-```
-
-Apply formatting:
-
-```powershell
-.\tools\postman\format_collection.ps1 -Fix
-```
-
-Compact/minified output (optional):
-
-```powershell
-.\tools\postman\format_collection.ps1 -Fix -Compact
-```
-
-## Linux / macOS (Shell)
-
-Formatter wrapper:
+## Visualizer Script Sync
 
-- `tools/postman/format_collection.sh`
-
-If needed, make sure the shell wrapper is executable:
-
-```bash
-chmod +x tools/postman/format_collection.sh
-```
-
-Check formatting only (no file changes):
+Use this tool to check/update embedded visualizer script code:
 
 ```bash
-tools/postman/format_collection.sh --check
-```
-
-Apply formatting:
-
-```bash
-tools/postman/format_collection.sh --fix
-```
-
-Compact/minified output (optional):
-
-```bash
-tools/postman/format_collection.sh --fix --compact
+source .venv/bin/activate
+tools/postman/sync_visualizers.py --check
+tools/postman/sync_visualizers.py --update
 ```
 
-## Alternate Collection Path
-
-Both wrappers support formatting a different collection file (for example `PyPNM-CMTS`).
-
-Linux / macOS:
+For `PyPNM-CMTS`:
 
 ```bash
-tools/postman/format_collection.sh --path postman/collections/PyPNM-CMTS.postman_collection.json --fix
-```
-
-Windows PowerShell:
-
-```powershell
-.\tools\postman\format_collection.ps1 -Path postman/collections/PyPNM-CMTS.postman_collection.json -Fix
+source .venv/bin/activate
+tools/postman/sync_visualizers.py --check --collection postman/collections/PyPNM-CMTS --visual-root visual/PyPNM-CMTS
+tools/postman/sync_visualizers.py --update --collection postman/collections/PyPNM-CMTS --visual-root visual/PyPNM-CMTS
 ```
 
-## Recommended Usage
-
-Run formatting before commit when the collection JSON changes:
+## Migration Note
 
-1. Format collection:
-   - `.\tools\postman\format_collection.ps1 -Fix`
-2. Sync visualizer scripts (if visual HTML changed):
-   - `tools/postman/sync_visualizers.py --update`
-3. Regenerate visual docs (if visual HTML/JSON changed):
-   - `tools/docs/build_visual_docs.py`
+Legacy single-file Postman collection JSON exports are not the primary artifact in this repo. Prefer editing YAML request files directly.

docs/postman-import-and-navigation.md

@@ -2,63 +2,68 @@
 
 Use this guide after installing Postman and cloning the repository.
 
-## Import Files Into Postman
+Required Postman version: **Postman Desktop v12+**.
 
-In Postman, import the following files:
+## Local-Mode Source of Truth
 
-- [`postman/collections/PyPNM.postman_collection.json`](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/collections/PyPNM.postman_collection.json)
-- [`postman/collections/PyPNM-CMTS.postman_collection.json`](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/collections/PyPNM-CMTS.postman_collection.json)
-- [`postman/environments/PyPNM Remote Server.postman_environment.json`](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/environments/PyPNM%20Remote%20Server.postman_environment.json)
-- [`postman/globals/workspace.postman_globals.json`](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/globals/workspace.postman_globals.json)
+This repository uses Postman local-mode file artifacts:
 
-Recommended import flow:
+- Collections: `postman/collections/<collection>/.../*.request.yaml`
+- Environments: `postman/environments/*.environment.yaml`
+- Globals: `postman/globals/*.globals.yaml`
+
+Do not expect a single `*.postman_collection.json` export as the primary source.
+
+## Open In Postman
+
+Recommended flow:
 
 1. Open Postman Desktop
-2. Click `Import`
-3. Select `Files`
-4. Choose the files listed above
-5. Confirm import
+2. Use local mode / open workspace from your cloned repository
+3. Point Postman to this repository root so it can read `postman/` YAML artifacts
 
-## Configure Base URL / Globals
+## Configure Base URL / Variables
 
-Set `pypnm_url` in Postman Globals.
+Set `pypnm_url` in globals (or equivalent environment variable if your workspace uses environment scope).
 
 Example:
 
 - `http://127.0.0.1:8000`
 
 Important:
 
-- Collection requests use `{{pypnm_url}}` (global variable)
-- The provided environment file includes `base_url`
-- If you prefer environment-only configuration, update the collection requests to use `{{base_url}}`
+- Request URLs in this repo use `{{pypnm_url}}` by default.
+- Keep variable syntax in Postman form (`{{var}}`).
 
-## Navigate the Imported Content
+## Navigate Main Collections
 
-### Collections
+- `postman/collections/PyPNM/`
+- `postman/collections/PyPNM-CMTS/`
 
-- `PyPNM` (primary collection)
-- `PyPNM-CMTS` (placeholder shell)
-
-### Good First Request
+## Good First Request
 
 Use a simple health check first:
 
-1. Open [`PyPNM` collection](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/collections/PyPNM.postman_collection.json)
-2. Open `Health` folder
-3. Open `Health` request
+1. Open collection `PyPNM`
+2. Open folder `Health`
+3. Open request `Health.request.yaml` (`name: Health`)
 4. Confirm `pypnm_url` is set
 5. Click `Send`
 
-### Common Next Areas
+## Common Next Areas
 
 - `SingleCapture` for single-capture workflows and visualizers
 - `MultiCapture` for multi-capture operations and analysis flows
-- `FileManager` for file workflow endpoints
+- `PNM/Files` for file workflow endpoints
 - `System` / `Health` for service checks and system actions
 
-## Troubleshooting Import Setup
+## Troubleshooting
+
+- If variables appear unresolved, confirm globals/environment YAML loaded in local mode.
+- If requests fail immediately, verify `pypnm_url` and authentication-related variables.
+- If visual output looks stale, run:
 
-- If requests fail immediately, confirm `pypnm_url` is set in [Globals (`workspace.postman_globals.json`)](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/globals/workspace.postman_globals.json)
-- If variables appear unresolved, verify [`workspace.postman_globals.json`](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/globals/workspace.postman_globals.json) imported successfully
-- If you use the environment value (`base_url`) instead, verify the imported environment [`PyPNM Remote Server.postman_environment.json`](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/environments/PyPNM%20Remote%20Server.postman_environment.json) and ensure request URLs in [`PyPNM.postman_collection.json`](https://github.com/PyPNMApps/Postman-PyPNMApps-API/blob/main/postman/collections/PyPNM.postman_collection.json) were updated from `{{pypnm_url}}`
+```bash
+source .venv/bin/activate
+tools/postman/sync_visualizers.py --check
+```

docs/postman-install.md

@@ -1,5 +1,10 @@
 # Install Postman Desktop (Ubuntu and Windows)
 
+## Required Version
+
+- Use **Postman Desktop v12 or newer** for this repository.
+- This repo uses local-mode YAML collections (`*.request.yaml`) aligned with Postman Collection v3 workflows.
+
 ## Download
 
 - Official Postman downloads page: `https://www.postman.com/downloads/`

docs/tools.md

@@ -5,7 +5,7 @@ Project utilities live under `tools/` to keep the repository root clean.
 See also:
 
 - `docs/visual-workflow.md` for the recommended visual edit -> Postman sync -> docs workflow
-- `docs/postman-collection-format.md` for Postman collection JSON formatting (Windows-first usage)
+- `docs/postman-collection-format.md` for local YAML Postman conventions and migration notes
 
 ## Setup
 
@@ -80,9 +80,9 @@ Path:
 
 Purpose:
 
-- Syncs Postman collection visualizer test scripts from `visual/PyPNM/**/*.html`
-- Treats Postman request paths/names as the source of truth for matching visual HTML paths
-- Detects drift between `visual/` HTML and `postman/collections/PyPNM.postman_collection.json`
+- Syncs Postman request visualizer scripts from `visual/**/*.html` into local YAML request files
+- Treats request header mapping (`// Postman Visualizer: ...`) as source for HTML path resolution
+- Detects drift between `visual/` HTML and `postman/collections/**/.request.yaml`
 
 Usage:
 
@@ -93,36 +93,8 @@ tools/postman/sync_visualizers.py --update
 
 Modes:
 
-- `--check` : read-only, exits non-zero if collection visualizer scripts drift from `visual/`
-- `--update` : updates collection visualizer scripts in place from matched HTML files
-
-## Postman Collection Formatter
-
-Paths:
-
-- `tools/postman/format_collection.py`
-- `tools/postman/format_collection.sh`
-- `tools/postman/format_collection.ps1`
-
-Purpose:
-
-- Formats Postman collection JSON with consistent style and LF line endings
-- Detects Postman collection schema version (`v2.0` / `v2.1`)
-- Normalizes non-finite values (`NaN` / `Infinity`) to `null` for valid JSON output
-
-Windows (default examples):
-
-```powershell
-.\tools\postman\format_collection.ps1 -Check
-.\tools\postman\format_collection.ps1 -Fix
-```
-
-Linux/macOS:
-
-```bash
-tools/postman/format_collection.sh --check
-tools/postman/format_collection.sh --fix
-```
+- `--check` : read-only, exits non-zero if visualizer scripts drift from `visual/`
+- `--update` : updates request YAML `scripts[].code` from matched HTML files
 
 ## Version Bump Tool
 

docs/user-guide.md

@@ -2,18 +2,20 @@
 
 ## Overview
 
-This repository provides Postman collections, environment, globals, and visualizer examples for PyPNM API workflows.
+This repository provides Postman local-mode artifacts and visualizer examples for PyPNM API workflows.
+
+Required Postman version: **Postman Desktop v12+** (local YAML collection support).
 
 Main artifacts:
 
-- `postman/collections/PyPNM.postman_collection.json`
-- `postman/collections/PyPNM-CMTS.postman_collection.json` (placeholder shell)
-- `postman/environments/PyPNM Remote Server.postman_environment.json`
-- `postman/globals/workspace.postman_globals.json`
+- `postman/collections/PyPNM/**.request.yaml`
+- `postman/collections/PyPNM-CMTS/**.request.yaml`
+- `postman/environments/PyPNM Remote Server.environment.yaml`
+- `postman/globals/workspace.globals.yaml`
 
 ## Install Postman
 
-1. Follow `docs/postman-install.md` for Ubuntu/Windows download and install steps
+1. Follow `docs/postman-install.md` for Ubuntu/Windows install steps
 2. Install and open Postman
 
 ## Clone Repository
@@ -23,17 +25,17 @@ git clone https://github.com/PyPNMApps/Postman-PyPNMApps-API.git
 cd Postman-PyPNMApps-API
 ```
 
-## Import Into Postman
+## Load Postman Assets
 
 Follow `docs/postman-import-and-navigation.md` for:
 
-- importing collections/environment/globals
+- opening local-mode YAML collections/environment/globals
 - configuring `pypnm_url`
 - navigating the `PyPNM` collection and first request
 
 ## Configure URL and Variables
 
-Minimum globals commonly needed:
+Minimum variables commonly needed:
 
 - `pypnm_url`
 - `cm_ip_address`
@@ -62,7 +64,7 @@ Health check:
 2. Set `pypnm_url`
 3. Click `Send`
 
-Then try a single capture request such as `Ofdm-RxMER-GetCapture`.
+Then try a single-capture request such as `Ofdm-RxMER-GetCapture`.
 
 ## Visualizer Notes