From 820915bed025df82f507c81604893df3ab11a082 Mon Sep 17 00:00:00 2001
From: cdc-ap66 <ap66@cdc.gov>
Date: Tue, 18 Nov 2025 13:05:56 +0000
Subject: [PATCH 1/2] doc updates

---
 docs/data_user_guide.md | 67 +++++++++++++++++++++++++++++++++++++----
 mkdocs.yaml             |  1 +
 2 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/docs/data_user_guide.md b/docs/data_user_guide.md
index 88fd2d2..c51e581 100644
--- a/docs/data_user_guide.md
+++ b/docs/data_user_guide.md
@@ -57,12 +57,12 @@ df = datacat.private.scenarios.covid19vax_trends.load.get_dataframe(
 )
 ```
 
-In order to see what versions are available, use the data catalog's convenient namespace methods:
+To see what versions are available, use the data catalog's convenient namespace methods:
 
 ```python
 >>> from cfa.dataops import datacat
->>> # these follow hierarchical naming created using the dataset
->>> # config TOML, so extract or load are the makes assigned to
+>>> # These follow hierarchical naming created using the dataset
+>>> # config TOML, so extract or load are the names assigned to
 >>> # raw or transformed datasets per the get_data function
 >>> datacat.private.scenarios.covid19vax_trends.load.get_versions()
 ['2025-06-03T17-59-16',
@@ -94,13 +94,68 @@ vax_df = datacat.private.scenarios.covid19vax_trends.load.get_dataframe()
 raw_vax = datacat.private.scenarios.covid19vax_trends.extract.get_dataframe()
 ```
 
-### Seroprevalence Data
+### Fetching Versions within a Range
+
+When `get_dataframe(...)` completes successfully, it prints a short confirmation line like:
+
+Used version(s): [...]
+
+Examples:
 
 ```python
 from cfa.dataops import datacat
 
-# Get as polars DataFrame
-sero_df = datacat.private.scenarios.seroprevalence.load.get_dataframe(output="polars")
+# newest match in the range (single version)
+df = datacat.private.scenarios.covid19vax_trends.load.get_dataframe(
+   version=">=2025-05-01,<2025-06-01"
+)
+```
+
+*Console output (example):*
+```
+Used version(s): '2025-05-30T19-55-51'
+```
+
+```python
+# oldest match in the same range (newest=False)
+df_old = datacat.private.scenarios.covid19vax_trends.load.get_dataframe(
+   version=">=2025-05-01,<2025-06-01", newest=False
+)
+```
+
+*Console output (example):*
+```
+Used version(s): '2025-05-30T14-50-36'
+```
+
+```python
+# Fetch all matches and concatenate all tables
+df_v = datacat.private.scenarios.covid19vax_trends.load.get_dataframe(
+   version=">=2025-05-01,<2025-06-01",
+   newest=None
+)
+```
+
+*Console output (example):*
+```
+Used version(s): ['2025-05-30T19-55-51', '2025-05-30T14-50-36']
+```
+
+Use the helper `version_matcher` (from `cfa.dataops.utils`) to experiment with version boundary logic to see what matches occur prior to loading large datasets into memory.
+
+```python
+>>> from cfa.dataops.utils import version_matcher
+>>> available_versions = ['1.0', '1.1', '1.2', '2.0']
+>>> version_matcher('>=1.1,<2.0', available_versions)
+'1.2'
+>>> version_matcher('>=1.1,<2.0', available_versions, newest=False)
+'1.1'
+>>> version_matcher('latest', available_versions)
+'2.0'
+>>> version_matcher('~=1', available_versions)
+'1.2'
+>>> version_matcher('>=1.1,<2.0', available_versions, newest=None)
+['1.2', '1.1']
 ```
 
 ## Common Issues
diff --git a/mkdocs.yaml b/mkdocs.yaml
index b9bf8be..6e9d97c 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -7,6 +7,7 @@ nav:
   - data_user_guide.md
   - data_developer_guide.md
   - report_generation.md
+  - cli_tools.md
 
 repo_url: https://github.com/cdcgov/cfa-dataops
 repo_name: cfa-dataops

From ab1323d628103ebc978f5b026a977116b68d925d Mon Sep 17 00:00:00 2001
From: cdc-ap66 <ap66@cdc.gov>
Date: Tue, 18 Nov 2025 13:06:09 +0000
Subject: [PATCH 2/2] version bump

---
 changelog.md   | 6 ++++++
 pyproject.toml | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/changelog.md b/changelog.md
index 97198ad..de25d00 100644
--- a/changelog.md
+++ b/changelog.md
@@ -8,6 +8,12 @@ The versioning pattern is `YYYY.MM.DD.micro(a/b/{none if release})
 
 ---
 
+## [2025.11.18.0a]
+
+### Updated
+
+- `docs/data_user_guide.md` and added cli documentation to mkdocs nav.
+
 ## [2025.11.13.0a]
 
 ### Added
diff --git a/pyproject.toml b/pyproject.toml
index 8a4bc65..f4b9ccd 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "cfa.dataops"
-version = "2025.11.13.0a"
+version = "2025.11.18.0a"
 description = "Data cataloging, ETL, modeling, verification, and validation for CFA"
 authors = [
     { name = "Phil Rogers", email = "ap66@cdc.gov" },