paramify · 21tmccauley · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,9 @@
 __pycache__/
 *.py[cod]
 *.egg-info/
+build/
+dist/
+*.whl
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,53 @@ schemas and the `paramify` CLI — not the internal code.
 
 ## [Unreleased]
 
+### Fixed
+
+- The TUI welcome screen's startup checks no longer fail on an installed
+  (pipx/brew) copy: the checkout-only "repo root" check is now "content
+  roots" (green when fetchers come from the installed bundle and/or user
+  dir), and the catalog/uploader checks answer without a checkout. Creating
+  a manifest from the welcome screen also works installed (lands in
+  `./manifests/`).
+
+## [0.3.0-rc.1] - 2026-07-13
+
+The distributable-install release candidate: the tool now works without a
+clone. No schema changes — the envelope `schema_version` stays `1.0` and the
+`fetcher.yaml` / category / manifest contracts are untouched.
+
+### Added
+
+- **The overlay distribution model** (`docs/distribution_design.md`). Built-ins
+  ship read-only inside the package (`framework/_bundled/`); user-created
+  fetchers and overrides live in `$PARAMIFY_HOME/fetchers/` and shadow
+  built-ins via an ordered search path (`$PARAMIFY_FETCHERS_PATH` → dev
+  checkout → user dir → installed bundle). Upgrades never write to the user
+  dir. The earlier workspace-sync design is preserved under `docs/deferred/`.
+- `paramify create <category>/<name>` — scaffold a new fetcher into your user
+  dir from the shipped template; `--category-file` also scaffolds the category
+  file for a brand-new platform.
+- `paramify customize <fetcher>` — copy-on-write override of a built-in, with
+  a sidecar so `paramify doctor` can flag the override when the original
+  changes upstream.
+- `paramify doctor` gains a distribution section: tool version, install path,
+  user dir, content roots, shadows, stale/orphaned overrides, and invalid
+  fetchers.
+- **The wheel is a real artifact**: schemas, the KSI reference, TUI styles,
+  the uploader, and the full content bundle ship in it — `pipx install` works
+  from a bare machine. A Homebrew tap formula template lives under
+  `packaging/brew/`.
+
+### Changed
+
+- Discovery is refuse-don't-crash: a broken `fetcher.yaml` is skipped and
+  reported instead of aborting every command; cross-root name collisions are
+  reported as shadows, never resolved silently.
+- Fetcher child processes get the running interpreter's `bin/` prepended to
+  `PATH`, so venv-installed CLIs (e.g. a pipx-injected `checkov`) resolve.
+- The TUI works without a checkout (installed mode); the missing-textual hint
+  now gives correct pipx/pip commands.
+
 ## [0.2.1-beta] - 2026-07-10
 
 ### Changed
@@ -72,6 +119,7 @@ change before 1.0 (see [`docs/versioning.md`](docs/versioning.md)).
 - TUI restyled — border titles, status pills, denser controls, and hatched empty
   states.
 
-[Unreleased]: https://github.com/paramify/paramify-fetchers/compare/v0.2.1-beta...HEAD
+[Unreleased]: https://github.com/paramify/paramify-fetchers/compare/v0.3.0-rc.1...HEAD
+[0.3.0-rc.1]: https://github.com/paramify/paramify-fetchers/compare/v0.2.1-beta...v0.3.0-rc.1
 [0.2.1-beta]: https://github.com/paramify/paramify-fetchers/compare/v0.2.0-beta...v0.2.1-beta
 [0.2.0-beta]: https://github.com/paramify/paramify-fetchers/releases/tag/v0.2.0-beta
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -0,0 +1,13 @@
+# sdist completeness: setup.py assembles framework/_bundled/ from fetchers/ and
+# examples/ at build time, so an sdist (or the GitHub source tarball) must carry
+# both, plus the core data files, or a wheel built from it comes out hollow.
+graft fetchers
+graft examples
+graft framework/schemas
+graft framework/reference
+graft framework/tui/styles
+graft uploaders
+include requirements.txt
+
+prune fetchers/logos
+global-exclude __pycache__ *.py[cod] .DS_Store
diff --git a/docs/deferred/workspace_sync_design.md b/docs/deferred/workspace_sync_design.md
diff --git a/docs/distribution_design.md b/docs/distribution_design.md
diff --git a/docs/releasing.md b/docs/releasing.md
@@ -57,12 +57,24 @@ Using `X.Y.Z` as the version (no `v` in files; the **tag** is `vX.Y.Z`).
    ```
 
    GitHub automatically attaches the **source code** as `.tar.gz` and `.zip` to
-   every release — that is our release artifact for now (see
-   [Artifacts](#artifacts)). Add `--generate-notes` if you also want GitHub's
+   every release. Add `--generate-notes` if you also want GitHub's
    auto-generated commit/PR list appended.
 
-7. **Verify:** `gh release view vX.Y.Z` — confirm the notes, the tag, and that
-   the source archives are attached.
+7. **Build and attach the wheel** (the pipx-installable artifact — see
+   [Artifacts](#artifacts)). The `setup.py` build hook assembles the
+   `framework/_bundled/` content snapshot into it:
+
+   ```bash
+   .venv/bin/pip wheel --no-deps --no-build-isolation -w dist .
+   gh release upload vX.Y.Z dist/*.whl
+   ```
+
+8. **Bump the Homebrew tap** (if published): stamp the new tarball url/sha256
+   and regenerate the python resources — see
+   [`packaging/brew/README.md`](../packaging/brew/README.md).
+
+9. **Verify:** `gh release view vX.Y.Z` — confirm the notes, the tag, the
+   source archives, and the wheel.
 
 ## Pre-releases
 
@@ -80,13 +92,31 @@ Use `-rc.N` (release candidate) or `-beta.N`. These sort before the final
 
 ## Artifacts
 
-- **Now:** the GitHub-attached **source tarball/zip**. The supported install is
-  from source (`pip install -e .`), so the source archive is the artifact.
-- **Deferred:** wheel/sdist + PyPI publishing. Blocked on the editable-only /
-  cwd-repo-root packaging issue (schemas resolve via the discovered repo root,
-  and fetchers execute as subprocesses out of `fetchers/`, which a plain wheel
-  doesn't ship). Revisit when that's fixed; a build+publish step then slots into
-  step 6.
+- **Source tarball/zip** — attached by GitHub automatically. Installs work from
+  source (`pip install .` — the build hook assembles the content bundle) and
+  editable in a clone (`pip install -e .`).
+- **Wheel** — built and attached in step 7; carries the engine, schemas, the
+  `framework/_bundled/` content snapshot, and the uploader. This is the
+  **pipx** path (the universal install: Mac/Windows/Linux):
+
+  ```bash
+  pipx install https://github.com/paramify/paramify-fetchers/releases/download/vX.Y.Z/paramify_fetchers-X.Y.Z-py3-none-any.whl
+  ```
+
+  Upgrading to a new release is `pipx install --force <new wheel url>`.
+  Caveat (found in dist testing): pipx ≥ 1.15 with the uv backend can fail
+  `--force` into an existing venv (`uv venv` refuses to overwrite, exit 1,
+  old version left in place) — prepend `UV_VENV_CLEAR=1`, or
+  `pipx uninstall paramify-fetchers` first.
+
+  (The former blocker — cwd-repo-root schemas, unshipped fetchers — was removed
+  by the overlay distribution work; see `docs/distribution_design.md`.)
+- **Homebrew tap** — the Mac/Linux convenience layer on top; can also declare
+  the external CLIs (`aws`/`kubectl`/`jq`/`git`/`checkov`) as dependencies.
+  Formula template + bump procedure: [`packaging/brew/`](../packaging/brew/README.md).
+- **Deferred: PyPI publishing.** Nothing blocks it anymore technically; it's a
+  distribution-channel decision (name squatting, support expectations), not a
+  packaging one.
 
 ## What a release does *not* touch