docs: Gitea PyPI install paths and publish automation

Add make package-check/publish-gitea, tag-triggered Gitea Actions workflow,
PACKAGE_RELEASE.md, and update README/GETTING_STARTED install instructions
for the Coulomb registry (v1.1.0+).

.gitea/workflows/publish-python-package.yml

@@ -0,0 +1,37 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install packaging tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Upload to Gitea PyPI
+        env:
+          TWINE_USERNAME: ${{ secrets.GITEA_PACKAGE_USER }}
+          TWINE_PASSWORD: ${{ secrets.GITEA_PACKAGE_TOKEN }}
+        run: >-
+          python -m twine upload
+          --repository-url https://gitea.coulomb.social/api/packages/coulomb/pypi
+          dist/*

Makefile

@@ -1,11 +1,14 @@
 # Makefile for Kaizen Agentic development tasks
 
-.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local install-global standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish release-finalize release-rollback
+.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local install-global standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish publish-gitea package-check release-finalize release-rollback
 
 # Variables
 VENV = .venv
 VENV_PYTHON = $(VENV)/bin/python
 VENV_PIP = $(VENV)/bin/pip
+GITEA_PACKAGE_OWNER ?= coulomb
+GITEA_PYPI_REPOSITORY_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi
+GITEA_PYPI_SIMPLE_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi/simple/
 
 # Default target
 help:
@@ -43,8 +46,10 @@ help:
 	@echo "Release Management:"
 	@echo "  release-check   - Validate release readiness (tests, linting, version consistency)"
 	@echo "  release-prepare - Prepare release (update versions, build packages)"
+	@echo "  package-check   - Build and validate wheel/sdist with twine"
+	@echo "  publish-gitea   - Publish dist/* to Coulomb Gitea PyPI registry"
 	@echo "  release-test    - Test publication workflow using TestPyPI"
-	@echo "  release-publish - Publish to production PyPI"
+	@echo "  release-publish - Publish to production PyPI (pypi.org)"
 	@echo "  release-finalize - Post-release tasks (tags, GitHub release, documentation)"
 	@echo "  release-rollback - Emergency rollback procedures"
 	@echo ""
@@ -915,8 +920,24 @@ release-prepare: release-check clean
 	ls -la dist/ | grep "$$VERSION" || echo "   • Package files:"; ls -la dist/; \
 	echo ""; \
 	echo "💡 Next steps:"; \
-	echo "   • Run 'make release-test' to test publication"; \
+	echo "   • Run 'make publish-gitea' for Coulomb Gitea PyPI"; \
-	echo "   • Run 'make release-publish' for production release"
+	echo "   • Run 'make release-test' to test publication on TestPyPI"; \
+	echo "   • Run 'make release-publish' for pypi.org (when configured)"
+
+# Build and validate distributions
+package-check: release-prepare
+	$(VENV_PYTHON) -c "import twine" 2>/dev/null || $(VENV_PIP) install twine
+	$(VENV_PYTHON) -m twine check dist/*
+
+# Publish to Coulomb Gitea PyPI registry
+publish-gitea: package-check
+ifndef TWINE_USERNAME
+	$(error TWINE_USERNAME is required (e.g. export TWINE_USERNAME=<gitea-user>))
+endif
+ifndef TWINE_PASSWORD
+	$(error TWINE_PASSWORD is required (e.g. export TWINE_PASSWORD=$$GITEA_API_TOKEN))
+endif
+	$(VENV_PYTHON) -m twine upload --repository-url "$(GITEA_PYPI_REPOSITORY_URL)" dist/*
 
 # Test publication workflow using TestPyPI
 release-test: release-prepare
@@ -1026,4 +1047,4 @@ release-rollback: $(VENV)/bin/activate
 	echo "   • Always test with TestPyPI first"; \
 	echo "   • Use staging/preview environments"; \
 	echo "   • Implement automated quality gates"; \
-	echo "   • Consider pre-release versions for testing"
+	echo "   • Consider pre-release versions for testing"

README.md

@@ -37,13 +37,21 @@ python3 -m build && make install-local
 source .venv/bin/activate  # Required for each session
 ```
 
-**From PyPI (Coming Soon):**
+**From Gitea PyPI (v1.1.0+):**
 ```bash
-pip install kaizen-agentic  # Available after v1.0.0 publication
+export GITEA_PACKAGE_USER=<gitea-user>
-# or
+export GITEA_PACKAGE_TOKEN=<package-token>
-pipx install kaizen-agentic  # Recommended for global CLI tools
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+
+# or global CLI via pipx
+pipx install kaizen-agentic \
+  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```
 
+See [docs/PACKAGE_RELEASE.md](docs/PACKAGE_RELEASE.md) for release and CI details.
+
 ### Your First Project (New Users)
 **👋 New to Kaizen Agentic?** Follow our [Hello World Tutorial](docs/HELLO_WORLD_TUTORIAL.md) for a complete step-by-step guide.
 

SCOPE.md

@@ -42,7 +42,7 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE
 - Project-specific implementation (agents guide work; they do not build the target software)
 - Custodian State Hub, MCP server code, or cross-domain governance (consumed, not owned)
 - Full KaizenGuidance codemod pipeline (vision in `wiki/KaizenGuidance.md`; not yet implemented)
-- PyPI publication pipeline (v1.0.2 released locally; public PyPI distribution still pending)
+- Gitea PyPI publication (`make publish-gitea`, tag workflow); public pypi.org optional
 
 ---
 
@@ -163,4 +163,4 @@ keywords: [kaizen, intent, template, optimization, digital-talent-agency]
 ## Notes
 
 - `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` (16 files) is what pip installs ship — coach, sys-medic, scope-analyst, and optimization are not yet bundled
-- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality
+- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality

docs/GETTING_STARTED.md

@@ -57,16 +57,22 @@ make install-global
 # CLI available from any directory
 ```
 
-**Option D: From PyPI (Coming Soon)**
+**Option D: From Gitea PyPI (v1.1.0+)**
 
 ```bash
-# Will be available once v1.0.0 is published
+export GITEA_PACKAGE_USER=<gitea-user>
-pip install kaizen-agentic
+export GITEA_PACKAGE_TOKEN=<package-token>
-# or
+
-pipx install kaizen-agentic  # Recommended for global CLI tools
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+
+# or global CLI via pipx
+pipx install kaizen-agentic \
+  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```
 
-> **📦 Release Status**: v1.0.0 is ready for publication. Use `make install-global` for system-wide availability.
+> **📦 Registry**: Published on the Coulomb Gitea PyPI registry. Dependencies resolve
+> from public PyPI via `--extra-index-url`. See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md).
 
 ### 2. Verify Installation
 
@@ -265,7 +271,9 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: '3.8'
-      - run: pip install kaizen-agentic
+      - run: >-
+          pip install kaizen-agentic
+          --extra-index-url "https://${{ secrets.GITEA_PACKAGE_USER }}:${{ secrets.GITEA_PACKAGE_TOKEN }}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
       - run: kaizen-agentic validate
 ```
 
@@ -405,7 +413,8 @@ kaizen-agentic status
 # New team member setup
 git clone project-repo
 cd project-repo
-pip install kaizen-agentic  # or add to requirements
+# see Option D for GITEA_PACKAGE_USER / GITEA_PACKAGE_TOKEN and --extra-index-url
+pip install kaizen-agentic
 kaizen-agentic status       # See what agents are used
 kaizen-agentic validate     # Verify everything works
 
@@ -419,12 +428,16 @@ cat CLAUDE.md
 
 **"Command not found: kaizen-agentic"**
 ```bash
-# Install the package
+# Install from Gitea PyPI (same credentials as Option D)
-pip install kaizen-agentic
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 
 # Or if using virtual env:
 source .venv/bin/activate
-pip install kaizen-agentic
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```
 
 **"No agents directory found"**
@@ -463,4 +476,4 @@ Once you have agents installed:
 4. **Share with team**: Document which agents your project uses
 5. **Contribute back**: Report issues and suggest improvements
 
-The key insight is that **you don't need the Makefile targets to use agents effectively** - the `kaizen-agentic` CLI provides all the functionality you need. The Makefile targets are just convenient shortcuts for projects that have them.
+The key insight is that **you don't need the Makefile targets to use agents effectively** - the `kaizen-agentic` CLI provides all the functionality you need. The Makefile targets are just convenient shortcuts for projects that have them.

docs/PACKAGE_RELEASE.md

@@ -0,0 +1,80 @@
+# Python Package Release
+
+`kaizen-agentic` publishes as the `kaizen-agentic` Python package on the Coulomb
+Gitea PyPI registry. Public [pypi.org](https://pypi.org/) distribution is optional
+and not required for ecosystem use.
+
+## Install (consumers)
+
+Dependencies such as `pyyaml` resolve from public PyPI. Use Gitea as an extra index:
+
+```bash
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+```
+
+Global CLI via pipx:
+
+```bash
+pipx install kaizen-agentic \
+  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+```
+
+Do not commit tokenized index URLs. Inject credentials via environment variables or
+CI secrets.
+
+## Local Release
+
+Build and validate artifacts:
+
+```bash
+make package-check
+```
+
+Publish to the Coulomb organization registry:
+
+```bash
+TWINE_USERNAME=<gitea-user> \
+TWINE_PASSWORD=<package-token> \
+make publish-gitea
+```
+
+Package upload endpoint:
+
+```text
+https://gitea.coulomb.social/api/packages/coulomb/pypi
+```
+
+Consumer simple index:
+
+```text
+https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
+```
+
+## Gitea Actions Release
+
+The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags
+matching `v*`. Configure these repository secrets before cutting a release:
+
+- `GITEA_PACKAGE_USER`
+- `GITEA_PACKAGE_TOKEN`
+
+Example:
+
+```bash
+git tag v1.2.0
+git push origin v1.2.0
+```
+
+## Public PyPI (optional)
+
+When pypi.org credentials are configured (`~/.pypirc` or `TWINE_PASSWORD` API
+token with `TWINE_USERNAME=__token__`):
+
+```bash
+make release-publish
+python -m twine upload dist/*
+```