Document installing FlowRoute from PyPI

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- First release published to PyPI as `flowroute`, installable with `pip install flowroute`.
 - Fail-closed production and shadow runtime modes.
 - Approved artifact manifests with compatibility and local checkpoint hash verification.
 - Atomic router bundle replacement and rollback with generation guards.

README.md

@@ -1,5 +1,6 @@
 # FlowRoute
 
+[![PyPI](https://img.shields.io/pypi/v/flowroute)](https://pypi.org/project/flowroute/)
 [![CI](https://github.com/open-first/FlowRoute/actions/workflows/ci.yml/badge.svg)](https://github.com/open-first/FlowRoute/actions/workflows/ci.yml)
 [![Docs](https://github.com/open-first/FlowRoute/actions/workflows/docs.yml/badge.svg)](https://open-first.github.io/FlowRoute/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
@@ -72,10 +73,16 @@ Requires Python 3.10 or newer.
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-pip install -e .
+pip install flowroute
+```
+
+The demo catalog is not shipped inside the package. Fetch it from the tagged source:
+
+```bash
+curl -O https://raw.githubusercontent.com/open-first/FlowRoute/v0.2.0/examples/workflows.yaml
 
 flowroute route \
-  --catalog examples/workflows.yaml \
+  --catalog workflows.yaml \
   --text "Where is order 4812?" \
   --debug
 ```
@@ -100,6 +107,12 @@ flowroute evaluate \
   --fail-on-error
 ```
 
+The fixture suite reads files from the repository, so clone it first:
+
+```bash
+git clone https://github.com/open-first/FlowRoute.git && cd FlowRoute
+```
+
 Run unit tests without installing development tools:
 
 ```bash
@@ -151,8 +164,8 @@ otherwise eligible workflows may be considered.
 ## HTTP API
 
 ```bash
-pip install -e ".[api]"
-flowroute serve --catalog examples/workflows.yaml --port 8000
+pip install "flowroute[api]"
+flowroute serve --catalog workflows.yaml --port 8000
 ```
 
 ```bash
@@ -243,7 +256,7 @@ See [Production mode](https://open-first.github.io/FlowRoute/operations/producti
 Install the ML extra:
 
 ```bash
-pip install -e ".[hf]"
+pip install "flowroute[hf]"
 ```
 
 ```python
@@ -271,6 +284,8 @@ The `training/` directory contains:
 - a Transformers three-class verifier entry point; and
 - model/dataset card templates with explicit `TBD` fields.
 
+These scripts ship only in the repository, so run them from a clone:
+
 ```bash
 PYTHONPATH=src python training/build_demo_data.py \
   --catalog examples/workflows.yaml \

docs/getting-started/installation.md

@@ -4,12 +4,12 @@ FlowRoute requires Python 3.10 or newer.
 
 ## Core router
 
-Create an isolated environment and install the package in editable mode:
+Create an isolated environment and install the published package:
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-pip install -e .
+pip install flowroute
 ```
 
 On Windows PowerShell, activate the environment with:
@@ -25,20 +25,23 @@ The core install provides:
 - the local TF-IDF retriever and lexical verifier; and
 - YAML catalog validation.
 
+It does **not** include the demo catalog, fixtures, or training scripts. Those live in the
+repository; see [From source](#from-source) if you need them.
+
 ## Optional extras
 
 === "HTTP API"
 
     ```bash
-    pip install -e ".[api]"
+    pip install "flowroute[api]"
     ```
 
     Adds FastAPI and Uvicorn for `flowroute serve`.
 
 === "Hugging Face"
 
     ```bash
-    pip install -e ".[hf]"
+    pip install "flowroute[hf]"
     ```
 
     Adds the learned inference backends. This install is significantly larger because it includes
@@ -47,42 +50,66 @@ The core install provides:
 === "Model training"
 
     ```bash
-    pip install -e ".[training]"
+    pip install "flowroute[training]"
     ```
 
-    Adds Datasets and Accelerate to the learned-backend dependencies.
+    Adds Datasets and Accelerate to the learned-backend dependencies. The training scripts
+    themselves ship only in the repository.
 
 === "Development"
 
     ```bash
     pip install -e ".[dev]"
     ```
 
-    Adds pytest, Ruff, mypy, build, and HTTPX.
+    Adds pytest, Ruff, mypy, build, and HTTPX. Run this from a clone, not against the published
+    package.
 
 === "Documentation"
 
     ```bash
     pip install -r requirements-docs.txt
     ```
 
-    Adds MkDocs and Material for MkDocs.
+    Adds MkDocs and Material for MkDocs. Requires a clone.
+
+## From source
+
+Work from a clone when you need the demo catalog, the fixture suite, the training scripts, or a
+development install:
+
+```bash
+git clone https://github.com/open-first/FlowRoute.git
+cd FlowRoute
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+An editable install points the `flowroute` command at your working tree, so source edits take
+effect without reinstalling.
 
 ## Verify the install
 
 ```bash
 flowroute --help
-PYTHONPATH=src python -m unittest discover -s tests -v
+python -c "import flowroute; print(flowroute.__version__)"
+```
+
+From a clone, also run the test suite:
+
+```bash
+pytest -q
 ```
 
 ## Dependency groups
 
 | Install | Main dependencies | Intended use |
 | --- | --- | --- |
-| `pip install -e .` | NumPy, Pydantic, PyYAML, regex, scikit-learn | Local baseline and library |
-| `pip install -e ".[api]"` | FastAPI, Uvicorn | HTTP service |
-| `pip install -e ".[hf]"` | Torch, Transformers, Sentence Transformers | Learned inference backends |
-| `pip install -e ".[training]"` | Datasets, Accelerate, and learned-backend dependencies | Dataset processing and training |
-| `pip install -e ".[dev]"` | pytest, Ruff, mypy, build, HTTPX | Development and tests |
+| `pip install flowroute` | NumPy, Pydantic, PyYAML, regex, scikit-learn | Local baseline and library |
+| `pip install "flowroute[api]"` | FastAPI, Uvicorn | HTTP service |
+| `pip install "flowroute[hf]"` | Torch, Transformers, Sentence Transformers | Learned inference backends |
+| `pip install "flowroute[training]"` | Datasets, Accelerate, and learned-backend dependencies | Dataset processing and training |
+| `pip install -e ".[dev]"` | pytest, Ruff, mypy, build, HTTPX | Development and tests (clone only) |
 
 Next: [route the first request](quickstart.md).

docs/getting-started/quickstart.md

@@ -1,12 +1,19 @@
 # Quickstart
 
-This walkthrough uses the included demo catalog.
+This walkthrough needs a catalog. The published package does not ship one, so fetch the demo
+catalog from the tagged source:
+
+```bash
+curl -O https://raw.githubusercontent.com/open-first/FlowRoute/v0.2.0/examples/workflows.yaml
+```
+
+Working from a clone instead? Use `examples/workflows.yaml` in place of `workflows.yaml` below.
 
 ## Route from the CLI
 
 ```bash
 flowroute route \
-  --catalog examples/workflows.yaml \
+  --catalog workflows.yaml \
   --text "Where is order 4812?" \
   --debug
 ```
@@ -30,7 +37,7 @@ Scores and latency vary with the catalog, backend, hardware, and calibration bun
 ```python
 from flowroute import FlowRouter, RouteRequest, WorkflowRegistry
 
-registry = WorkflowRegistry.from_yaml("examples/workflows.yaml")
+registry = WorkflowRegistry.from_yaml("workflows.yaml")
 router = FlowRouter(registry)
 
 result = router.route(
@@ -58,7 +65,12 @@ else:
 
 ## Run the fixture evaluation
 
+The fixture suite reads several files that ship only in the repository, so run it from a clone:
+
 ```bash
+git clone https://github.com/open-first/FlowRoute.git
+cd FlowRoute
+
 flowroute evaluate \
   --catalog examples/workflows.yaml \
   --calibration configs/calibration.yaml \

docs/guides/cli.md

@@ -57,7 +57,7 @@ The JSON result contains:
 ## Serve the API
 
 ```bash
-pip install -e ".[api]"
+pip install "flowroute[api]"
 flowroute serve \
   --catalog examples/workflows.yaml \
   --calibration configs/calibration.yaml \

docs/guides/http-api.md

@@ -6,7 +6,7 @@ intended for local development; production uses explicit settings and an authori
 ## Install and run
 
 ```bash
-pip install -e ".[api]"
+pip install "flowroute[api]"
 flowroute serve \
   --catalog examples/workflows.yaml \
   --calibration configs/calibration.yaml \

docs/index.md

@@ -27,6 +27,14 @@ of three typed outcomes and never executes the selected workflow.
     orchestrator must still check authorization, typed inputs, live preconditions,
     confirmation, and idempotency before performing side effects.
 
+## Install
+
+```bash
+pip install flowroute
+```
+
+Published on [PyPI](https://pypi.org/project/flowroute/). Requires Python 3.10 or newer.
+
 ## Start here
 
 1. [Install FlowRoute](getting-started/installation.md).