From 7cce7ede6a29c21e477ad2e37803939499fe552a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vincent=20Gr=C3=A9goire?= <vincent.gregoire@gmail.com>
Date: Sat, 22 Aug 2026 11:48:29 -0400
Subject: [PATCH 1/4] add pypi metadata: author, urls, keywords, classifiers,
 spdx license

also bump __version__ in src/iolaus/__init__.py alongside pyproject so the
two cannot drift.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 pyproject.toml | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 9557c76..8821231 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,36 @@ version = "0.1.0"
 description = "Decorator-based CLI + config + logging framework for research projects."
 readme = "README.md"
 requires-python = ">=3.11"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Vincent Grégoire", email = "vincent.gregoire@gmail.com" },
+]
+keywords = [
+    "cli",
+    "configuration",
+    "logging",
+    "research",
+    "reproducibility",
+    "data-analysis",
+    "dynaconf",
+    "typer",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
 dependencies = [
     "dynaconf>=3.2",
     "typer>=0.12",
@@ -24,6 +53,13 @@ docs = [
     "mkdocstrings[python]",
 ]
 
+[project.urls]
+Homepage = "https://github.com/vgreg/iolaus"
+Documentation = "https://www.vincentgregoire.com/iolaus/"
+Repository = "https://github.com/vgreg/iolaus"
+Issues = "https://github.com/vgreg/iolaus/issues"
+Changelog = "https://github.com/vgreg/iolaus/blob/main/CHANGELOG.md"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -50,3 +86,8 @@ tag = true
 filename = "pyproject.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "src/iolaus/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

From e860b223e6767f3a91ac8a750de429c4e855a1b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vincent=20Gr=C3=A9goire?= <vincent.gregoire@gmail.com>
Date: Sat, 22 Aug 2026 11:48:29 -0400
Subject: [PATCH 2/4] ignore .DS_Store and add 0.1.0 changelog entry

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .gitignore   |  3 +++
 CHANGELOG.md | 17 ++++++++++++++++-
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 09be0ef..7a9721c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -205,3 +205,6 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# macOS
+.DS_Store
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2d4eee5..b6eb091 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
-- Initial project scaffolding
+## [0.1.0] - 2026-08-22
+
+Initial release.
+
+### Added
+
+- `command()` decorator factory that registers a function as a Typer command and wires in configuration and run logging.
+- Configuration merging via Dynaconf: base settings, extra config files passed with `--config`, and individual key overrides passed with `--set` (using `__` for nested keys).
+- Timestamped run directories under `outputs/<command>/<date>/<time>/`, each containing a `run.log` and a `config.json` snapshot of the merged configuration.
+- Opt-in injection of `settings` and `run_dir`, only for functions that declare them in their signature.
+- Type annotations throughout, with a `py.typed` marker for downstream type checkers.
+
+[Unreleased]: https://github.com/vgreg/iolaus/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/vgreg/iolaus/releases/tag/v0.1.0

From fb5f6baccfa7691dfe0fa6929d4a5504406e36e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vincent=20Gr=C3=A9goire?= <vincent.gregoire@gmail.com>
Date: Sat, 22 Aug 2026 11:48:29 -0400
Subject: [PATCH 3/4] credit hydra as inspiration and link the documentation
 site

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md     |  8 ++++++++
 docs/index.md | 19 +++++++++++++++++++
 mkdocs.yml    |  2 ++
 3 files changed, 29 insertions(+)

diff --git a/README.md b/README.md
index c887b9e..4d02d9e 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@
 
 A lightweight Python framework for research data analysis projects. Iolaus wires together [Dynaconf](https://www.dynaconf.com/), [Typer](https://typer.tiangolo.com/), and a custom run-logging system into a single decorator-based API that adds automatic configuration management and reproducible run artifacts on every invocation.
 
+**Documentation:** [www.vincentgregoire.com/iolaus](https://www.vincentgregoire.com/iolaus/)
+
 ## Features
 
 - **Decorator-based API** — feels like FastAPI/Typer, with zero boilerplate
@@ -80,6 +82,12 @@ uv sync --all-extras
 uv run pytest
 ```
 
+## Relationship to Hydra
+
+Iolaus is inspired by [Hydra](https://hydra.cc/), which established the pattern of composable configuration files combined with timestamped output directories for research code. Iolaus is deliberately a lightweight alternative implementing only the subset of Hydra's features that I actually use in my own projects, built on Dynaconf and Typer rather than on OmegaConf.
+
+If Iolaus is not flexible enough, or if you need something it does not provide (config groups, multirun parameter sweeps, structured configs, object instantiation, or launcher plugins for clusters), you should use Hydra instead. It is a mature and well-documented project, and Iolaus makes no attempt to match its scope.
+
 ## License
 
 MIT
diff --git a/docs/index.md b/docs/index.md
index de7de57..0896d97 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -43,6 +43,25 @@ outputs/
             └── config.json
 ```
 
+## Relationship to Hydra
+
+Iolaus is inspired by [Hydra](https://hydra.cc/), which established the pattern of composable configuration files combined with timestamped output directories for research code. Iolaus is deliberately a lightweight alternative implementing only the subset of Hydra's features that I actually use in my own projects, built on [Dynaconf](https://www.dynaconf.com/) and [Typer](https://typer.tiangolo.com/) rather than on OmegaConf.
+
+The trade-off is scope. Iolaus gives you a decorator, config merging, and a run directory, and nothing else. Hydra gives you a much larger system:
+
+| | Iolaus | Hydra |
+| --- | --- | --- |
+| Config merging from files | Yes | Yes |
+| CLI key overrides | Yes | Yes |
+| Timestamped run directories | Yes | Yes |
+| Config groups and defaults lists | No | Yes |
+| Multirun and parameter sweeps | No | Yes |
+| Structured (typed) configs | No | Yes |
+| Object instantiation from config | No | Yes |
+| Launcher plugins (Slurm, Ray, etc.) | No | Yes |
+
+If Iolaus is not flexible enough, or if you need any of the features in the right-hand column, you should use Hydra instead. It is a mature and well-documented project, and Iolaus makes no attempt to match its scope.
+
 ## Next steps
 
 - [Getting Started](getting-started.md) — installation and first project
diff --git a/mkdocs.yml b/mkdocs.yml
index 590f822..385bb2b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,5 +1,6 @@
 site_name: Iolaus
 site_description: Decorator-based CLI, config, and logging framework for research projects.
+site_url: https://www.vincentgregoire.com/iolaus/
 repo_url: https://github.com/vgreg/iolaus
 repo_name: vgreg/iolaus
 
@@ -39,6 +40,7 @@ nav:
   - API Reference: api-reference.md
 
 markdown_extensions:
+  - tables
   - pymdownx.highlight
   - pymdownx.superfences
   - admonition

From 556c20bf25aa3a80047ef6b4a7704cafa06a21a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vincent=20Gr=C3=A9goire?= <vincent.gregoire@gmail.com>
Date: Sat, 22 Aug 2026 12:00:01 -0400
Subject: [PATCH 4/4] run publish job in the release environment and guard tag
 against version

trusted publishing is configured against the release environment, so the job
must declare it. also pin contents: read for checkout now that the permissions
block is job-scoped, and fail early when the pushed tag does not match the
version in pyproject.toml.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/publish.yml | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 0743330..1de90d3 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -4,12 +4,18 @@ on:
   push:
     tags: ["v*"]
 
-permissions:
-  id-token: write  # required for PyPI Trusted Publishing
-
 jobs:
   publish:
     runs-on: ubuntu-latest
+
+    environment:
+      name: release
+      url: https://pypi.org/p/iolaus
+
+    permissions:
+      contents: read
+      id-token: write  # required for PyPI Trusted Publishing
+
     steps:
       - uses: actions/checkout@v4
 
@@ -17,6 +23,16 @@ jobs:
 
       - run: uv sync --all-extras
 
+      - name: Check tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION=$(uv run python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match pyproject.toml version $VERSION"
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME matches version $VERSION"
+
       - name: Run tests
         run: uv run pytest