docs - fix install instructions and drop broken PyPI badge

README.md

@@ -1,6 +1,5 @@
 # Envars: Application Config as Code
 
-[![PyPI version](https://badge.fury.io/py/envars2.svg)](https://badge.fury.io/py/envars2)
 [![Documentation Status](https://readthedocs.org/projects/envars/badge/?version=latest)](https://envars.readthedocs.io/en/latest/?badge=latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -23,10 +22,20 @@ Stop juggling `.env` files and start treating your configuration like code.
 
 ## Installation
 
+`envars` is not published to PyPI — install it from this repository. The
+`envars` package on PyPI is an unrelated third-party project.
+
 ```bash
-pip install envars
+# pinned to a release tag (recommended)
+pip install "git+https://github.com/timeoutdigital/envars2@1.0.4"
+
+# or, to add it to a uv-managed project
+uv add "envars @ git+https://github.com/timeoutdigital/envars2@1.0.4"
 ```
 
+Drop the `@1.0.4` to install from the repository's default branch (currently
+`master`). Either form installs the `envars` command.
+
 ## Quick Start
 
 1.  **Initialize a new project:**
@@ -145,8 +154,8 @@ Here are some ideas for future enhancements that could make `envars` even more p
 To set up the development environment, clone the repository and install the dependencies using `uv`:
 
 ```bash
-git clone https://github.com/your-username/envars.git
-cd envars
+git clone https://github.com/timeoutdigital/envars2.git
+cd envars2
 uv sync
 ```
 

docs/getting-started.md

@@ -4,12 +4,16 @@ This tutorial will guide you through the basics of using `envars` to manage your
 
 ## 1. Installation
 
-First, install `envars` using `pip`:
+`envars` is not published to PyPI — install it from GitHub. (The `envars`
+package on PyPI is an unrelated third-party project.)
 
 ```bash
-pip install envars
+pip install "git+https://github.com/timeoutdigital/envars2@1.0.4"
 ```
 
+Drop the `@1.0.4` to install from the repository's default branch (currently
+`master`).
+
 ## 2. Initialize Your Project
 
 The `envars init` command is the best way to start a new project. It creates the `envars.yml` file with the basic structure.

docs/project/ARCHITECTURE.md

@@ -132,7 +132,7 @@ This guide will help new developers get up and running with the `envars2` projec
 
 1.  **Clone the repository:**
     ```bash
-    git clone https://github.com/your-username/envars2.git
+    git clone https://github.com/timeoutdigital/envars2.git
     cd envars2
     ```
 

docs/project/contributing.md

@@ -4,14 +4,16 @@ We welcome contributions from the community! Whether you're fixing a bug, improv
 
 ## Getting Started
 
-1.  **Fork the repository** on GitHub.
-2.  **Clone your fork** locally: `git clone https://github.com/your-username/envars.git`
-3.  **Install dependencies** for development. We use `uv` for package management.
+1.  **Clone the repository** locally: `git clone https://github.com/timeoutdigital/envars2.git`
+    Without write access to `timeoutdigital/envars2` you cannot push a branch to it —
+    fork the repository on GitHub first and clone your fork instead.
+2.  **Install dependencies** for development. We use `uv` for package management.
     ```bash
     pip install uv
     uv sync
     ```
-4.  **Create a new branch** for your changes: `git checkout -b my-feature-branch`
+3.  **Create a new branch** for your changes: `git checkout -b my-feature-branch`
+    (the `no-commit-to-branch` pre-commit hook blocks committing to `master`)
 
 ## Running Tests
 
@@ -39,8 +41,8 @@ uv run pre-commit install
 ## Submitting a Pull Request
 
 1.  **Commit your changes** with a clear and descriptive commit message.
-2.  **Push your branch** to your fork on GitHub: `git push origin my-feature-branch`
-3.  **Open a pull request** from your branch to the `main` branch of the original repository.
+2.  **Push your branch**: `git push origin my-feature-branch` — to your fork, if you cloned one.
+3.  **Open a pull request** from your branch to `master` on `timeoutdigital/envars2`.
 4.  In the pull request description, please explain the changes you made and why.
 
 Thank you for contributing!