DEVX-46: docs: add pyproject.toml dependency and pip.conf instructions for devx

README.md

@@ -59,24 +59,57 @@ up by bumping their devx dependency.
 
 ## Installation
 
-Install from the Gitea PyPI registry:
+devx is published to the Gitea PyPI registry at
+`https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple`.
+The registry is publicly readable — no authentication required to install.
+
+### Quick install (one-off)
 
 ```bash
 pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
 ```
 
-Or add the registry to your `pip.conf` / `pyproject.toml` and install normally:
+### Persistent configuration (recommended)
+
+Add the registry to `~/.pip/pip.conf` so `pip install devx` works without
+specifying `--index-url` every time:
+
+```ini
+[global]
+extra-index-url = https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
+```
+
+### As a dependency in another project
+
+To use devx as a dependency in your `pyproject.toml`, add the registry as an
+extra index and list devx in your dependencies:
+
+```toml
+[project]
+dependencies = [
+    "devx>=0.11.1",
+]
+
+[tool.pip]
+extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
+```
+
+Then install normally:
 
 ```bash
-pip install devx
+pip install -e .
 ```
 
+> **Note:** If your project requires a specific devx version, pin it in
+> `dependencies` (e.g., `"devx==0.11.1"`) or use a version constraint
+> (e.g., `"devx>=0.11.1,<0.12"`).
+
 ### Optional extras
 
 devx ships optional dependency groups for different use cases:
 
 ```bash
-pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit)
+pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit, build, twine)
 pip install "devx[molecule]"     # Molecule testing for Ansible projects
 pip install "devx[dev]"          # Full local development (ci + lint + build + twine)
 ```

docs/index.md

@@ -46,18 +46,49 @@ via environment variables and `pyproject.toml`, and inherit:
 
 ## Installation
 
-Install from the Gitea PyPI registry:
+devx is published to the Gitea PyPI registry at
+`https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple`.
+The registry is publicly readable — no authentication required to install.
+
+### Quick install (one-off)
 
 ```bash
 pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
 ```
 
-Optional extras:
+### Persistent configuration (recommended)
+
+Add the registry to `~/.pip/pip.conf`:
+
+```ini
+[global]
+extra-index-url = https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
+```
+
+Then `pip install devx` works without specifying `--index-url`.
+
+### As a dependency in another project
+
+Add devx to your `pyproject.toml` dependencies and configure the registry:
+
+```toml
+[project]
+dependencies = [
+    "devx>=0.11.1",
+]
+
+[tool.pip]
+extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
+```
+
+Pin a specific version if needed: `"devx==0.11.1"` or `"devx>=0.11.1,<0.12"`.
+
+### Optional extras
 
 ```bash
-pip install "devx[ci,lint]"      # CI runners and linting
+pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit, build, twine)
 pip install "devx[molecule]"     # Molecule testing for Ansible projects
-pip install "devx[dev]"          # Full local development
+pip install "devx[dev]"          # Full local development (ci + lint + build + twine)
 ```
 
 ## Architecture