Migrate kaizen distribution to Forgejo

2026-08-20 09:43:49 +02:00 · 2026-08-20 09:43:49 +02:00 · d4a4560a8d
commit d4a4560a8d
parent f027ee5492
34 changed files with 324 additions and 195 deletions
--- a/docs/AGENT_DISTRIBUTION.md
+++ b/docs/AGENT_DISTRIBUTION.md
@ -13,14 +13,11 @@ The Kaizen Agentic framework provides a comprehensive system for distributing an

 ## Installation

-Install the Kaizen Agentic package from the Coulomb Gitea PyPI registry:
+Install the Kaizen Agentic package from the Forgejo PyPI registry:

 ```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/"
+  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
 ```

 This provides the `kaizen-agentic` CLI tool for managing agents. See
--- a/docs/CLI_CHEAT_SHEET.md
+++ b/docs/CLI_CHEAT_SHEET.md
@ -4,14 +4,11 @@ Quick reference for the `kaizen-agentic` command-line tool.

 ## Installation

-From Coulomb Gitea PyPI (see [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md)):
+From Forgejo PyPI (see [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md)):

 ```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/"
+  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
 ```

 ## Core Commands
--- a/docs/FEEDBACK.md
+++ b/docs/FEEDBACK.md
@ -6,12 +6,12 @@ How to share bugs, ideas, and adoption experience for kaizen-agentic.

 | Channel | Use for |
 |---------|---------|
-| **Gitea Issues** | Bugs, features, general feedback (templates below) |
+| **Forgejo Issues** | Bugs, features, general feedback (templates below) |
 | **`kaizen-agentic feedback`** | Print links and template guidance from the CLI |
 | **Pull requests** | Code and agent-definition contributions (see CONTRIBUTING.md) |
 | **State Hub messages** | Cross-repo coordination between custodian agents (advanced) |

-## Gitea issue templates
+## Forgejo issue templates

 Choose a template when opening a new issue:

@ -19,7 +19,7 @@ Choose a template when opening a new issue:
 - **Feature request** — enhancements with proposed scope
 - **General feedback** — experience and adoption notes

-Repository: [coulomb/kaizen-agentic](https://gitea.coulomb.social/coulomb/kaizen-agentic/issues)
+Repository: [coulomb/kaizen-agentic](https://forgejo.coulomb.social/coulomb/kaizen-agentic/issues)

 ## CLI

@ -38,4 +38,4 @@ kaizen-agentic feedback --json   # machine-readable for tooling
 ## Privacy

 Do not include secrets, tokens, or private project content in public issues. Redact
-`.kaizen/` memory contents unless you intentionally share sanitized examples.
+`.kaizen/` memory contents unless you intentionally share sanitized examples.
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@ -12,7 +12,7 @@ This guide walks you through using Kaizen Agentic agents in any project, from in

 ```bash
 # Clone the repository
-git clone https://github.com/kaizen-agentic/kaizen-agentic.git
+git clone https://forgejo.coulomb.social/coulomb/kaizen-agentic.git
 cd kaizen-agentic

 # Set up development environment
@ -29,7 +29,7 @@ source .venv/bin/activate

 ```bash
 # Clone the repository and build package
-git clone https://github.com/kaizen-agentic/kaizen-agentic.git
+git clone https://forgejo.coulomb.social/coulomb/kaizen-agentic.git
 cd kaizen-agentic
 make setup-complete

@ -45,7 +45,7 @@ source .venv/bin/activate

 ```bash
 # Clone the repository and build package
-git clone https://github.com/kaizen-agentic/kaizen-agentic.git
+git clone https://forgejo.coulomb.social/coulomb/kaizen-agentic.git
 cd kaizen-agentic
 make setup-complete

@ -57,21 +57,18 @@ make install-global
 # CLI available from any directory
 ```

-**Option D: From Gitea PyPI (v1.1.0+)**
+**Option D: From Forgejo PyPI (v1.1.0+)**

 ```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/"
+  --extra-index-url https://forgejo.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/"
+  --pip-args="--extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

-> **📦 Registry**: Published on the Coulomb Gitea PyPI registry. Dependencies resolve
+> **📦 Registry**: Published on the Forgejo PyPI registry. Dependencies resolve
 > from public PyPI via `--extra-index-url`. See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md).

 ### 2. Verify Installation
@ -273,7 +270,7 @@ jobs:
          python-version: '3.8'
      - 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/"
+          --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
      - run: kaizen-agentic validate
 ```

@ -413,7 +410,7 @@ kaizen-agentic status
 # New team member setup
 git clone project-repo
 cd project-repo
-# see Option D for GITEA_PACKAGE_USER / GITEA_PACKAGE_TOKEN and --extra-index-url
+# see Option D for the Forgejo --extra-index-url
 pip install kaizen-agentic
 kaizen-agentic status       # See what agents are used
 kaizen-agentic validate     # Verify everything works
@ -428,16 +425,14 @@ cat CLAUDE.md

 **"Command not found: kaizen-agentic"**
 ```bash
-# Install from Gitea PyPI (same credentials as Option D)
-export GITEA_PACKAGE_USER=<gitea-user>
-export GITEA_PACKAGE_TOKEN=<package-token>
+# Install from Forgejo PyPI (same endpoint as Option D)
 pip install kaizen-agentic \
-  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/

 # Or if using virtual env:
 source .venv/bin/activate
 pip install kaizen-agentic \
-  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
 ```

 **"No agents directory found"**
--- a/docs/HELLO_WORLD_TUTORIAL.md
+++ b/docs/HELLO_WORLD_TUTORIAL.md
@ -9,14 +9,11 @@ This step-by-step tutorial will guide you through creating your first project wi

 ## Step 1: Install Kaizen Agentic

-From the Coulomb Gitea PyPI registry (dependencies resolve from public PyPI):
+From the Forgejo PyPI registry (dependencies resolve from public PyPI):

 ```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/"
+  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
 ```

 See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md) for pipx and release details.
@ -243,11 +240,9 @@ kaizen-agentic status

 **"kaizen-agentic: command not found"**
 ```bash
-# Same install as Step 1 (Gitea extra index — see PACKAGE_RELEASE.md)
-export GITEA_PACKAGE_USER=<gitea-user>
-export GITEA_PACKAGE_TOKEN=<package-token>
+# Same install as Step 1 (Forgejo extra index — see PACKAGE_RELEASE.md)
 pip install kaizen-agentic \
-  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
 ```

 **"make: command not found"**
--- a/docs/INTEGRATION_PATTERNS.md
+++ b/docs/INTEGRATION_PATTERNS.md
@ -52,7 +52,7 @@ invoke kaizen-agentic CLI commands.
 5. **Enable gradually** — set `enabled: true` per definition after a manual smoke test
   against a repo with `.kaizen/metrics/` populated.
 6. **Verify credentials** — scheduled runs need `kaizen-agentic` on PATH and any
-   Gitea PyPI extra index if the runner installs from registry (see PACKAGE_RELEASE.md).
+   Forgejo PyPI extra index if the runner installs from registry (see PACKAGE_RELEASE.md).

 **kaizen-agentic maintainer checklist:**

--- a/docs/PACKAGE_RELEASE.md
+++ b/docs/PACKAGE_RELEASE.md
@ -1,30 +1,27 @@
 # 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
+`kaizen-agentic` publishes as the `kaizen-agentic` Python package on the Forgejo
+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:
+Dependencies such as `pyyaml` resolve from public PyPI. Use Forgejo 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/"
+  --extra-index-url https://forgejo.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/"
+  --pip-args="--extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

-Do not commit tokenized index URLs. Inject credentials via environment variables or
-CI secrets.
+Consumer reads are anonymous. Keep publish credentials in Forgejo Actions secrets
+or inject them through the environment for a deliberate local release.

 ## Local Release

@ -37,53 +34,47 @@ make package-check
 Publish to the Coulomb organization registry:

 ```bash
-TWINE_USERNAME=<gitea-user> \
+TWINE_USERNAME=<forgejo-user> \
 TWINE_PASSWORD=<package-token> \
-make publish-gitea
+make publish-forgejo
 ```

 Package upload endpoint:

 ```text
-https://gitea.coulomb.social/api/packages/coulomb/pypi
+https://forgejo.coulomb.social/api/packages/coulomb/pypi
 ```

 Consumer simple index:

 ```text
-https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
+https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
 ```

-## Gitea repository secrets (one-time)
+## Forgejo repository secrets (one-time)

-Configure in Gitea: **Repository → Settings → Actions → Secrets**.
+Configure in Forgejo: **Repository → Settings → Actions → Secrets** (or use
+organization-level secrets when managed centrally).

 | Secret | Value |
 |--------|-------|
-| `PACKAGE_USER` | `tegwick` — Gitea username that owns the package token |
-| `PACKAGE_TOKEN` | Gitea API token named `inter-hub-pkg-rep` (`write:package`) |
+| `FORGEJO_PYPI_USER` | Forgejo username that owns the package token |
+| `FORGEJO_PYPI_TOKEN` | Forgejo token with package-write permission |

-Token custody (OpenBao):
+Discover credential ownership before requesting or rotating a token:

-```text
-platform/data/operators/inter-hub/package-management
-  → field: inter-hub-pkg-rep
+```bash
+warden route find "publish kaizen-agentic to Forgejo PyPI" --json
 ```

-Paste the **plaintext** token into the Gitea secret UI. `inter-hub-pkg-rep` is the
-token name in Gitea, not a username.
-
-Gitea rejects secret names prefixed with `GITEA_` — use `PACKAGE_USER` / `PACKAGE_TOKEN`
-(not `GITEA_PACKAGE_USER`). Workflows use `runs-on: haskelseed` and native `git clone`
-(no GitHub Marketplace actions).
+Never commit or copy the token into documentation, workplans, or State Hub.

 The publish workflow fails at the upload step when either secret is missing or
 invalid. Do not commit tokens to the repository.

-**Smoke-test (2026-06-16):** `workflow_dispatch` run #3042 authenticated successfully
-(`409 Conflict` on re-upload of `1.1.0` — expected). Root causes of earlier `401`s:
-wrong token (`GITEA_API_TOKEN` ≠ package token), wrong username (`inter-hub-pkg-rep`
-is a token name), and a stale org-level secret. Build uses `.build-venv` (PEP 668).
+**Verified (2026-08-20):** the Forgejo index serves `kaizen-agentic==1.4.0`.
+A fresh virtual environment installed it with `--no-cache-dir` and the CLI reported
+version `1.4.0`.

 Verify secrets without cutting a release:

@ -103,13 +94,13 @@ Before `git tag vX.Y.Z && git push origin vX.Y.Z`:
 - [ ] `make release-check` passes (tests, flake8, version consistency, agent parity)
 - [ ] `make package-check` builds and validates `dist/*`
 - [ ] `CHANGELOG.md` has a dated `[X.Y.Z]` section matching `pyproject.toml`
- [ ] `PACKAGE_USER` and `PACKAGE_TOKEN` secrets are set
+- [ ] `FORGEJO_PYPI_USER` and `FORGEJO_PYPI_TOKEN` secrets are set
 - [ ] Publish workflow smoke-tested via `workflow_dispatch` (or prior tag release)
 - [ ] `make agents-sync-package` run if `agents/` changed since last release

-## Gitea Actions Release
+## Forgejo Actions Release

-The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags
+The `.forgejo/workflows/publish-python-package.yml` workflow publishes on tags
 matching `v*`.

 Example:
@ -135,11 +126,11 @@ A runner that executes a scheduled kaizen agent task (fired by activity-core)
 needs:

 - **`kaizen-agentic` on PATH** — `pip install kaizen-agentic` (or `pipx install
-  kaizen-agentic`) using the Gitea PyPI extra index when installing from the
+  kaizen-agentic`) using the Forgejo PyPI extra index when installing from the
  internal registry:
  ```bash
  pip install kaizen-agentic \
-    --extra-index-url https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
+    --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
  ```
 - **Repo checkout reachable** at the `host_paths[<host>]` registered in State
  Hub, with a valid `.kaizen/schedule.yml` (`kaizen-agentic schedule validate`).
--- a/docs/TELEMETRY.md
+++ b/docs/TELEMETRY.md
@ -39,11 +39,11 @@ Potential v1.1 additions (not yet implemented):

 ## tele-mcp evaluation (deferred)

-[tele-mcp](https://gitea.coulomb.social/coulomb/tele-mcp) is a candidate MCP adapter
+[tele-mcp](https://forgejo.coulomb.social/coulomb/tele-mcp) is a candidate MCP adapter
 for IDE-level telemetry (WP-0001 note). Assess before depending on it. Project and
 fleet layers above satisfy INTENT's "measurable agents" requirement without tele-mcp.

 ## Feedback loop

-User experience feedback uses [FEEDBACK.md](FEEDBACK.md) and Gitea issue templates —
+User experience feedback uses [FEEDBACK.md](FEEDBACK.md) and Forgejo issue templates —
 separate from execution metrics.
--- a/docs/integrations/customer-engagement-playbook.md
+++ b/docs/integrations/customer-engagement-playbook.md
@ -2,7 +2,7 @@

 How kaizen-agentic supports a **customer engagement repo** for **improvement
 loops** (reference:
-[coulomb-loop](https://gitea.coulomb.social/coulomb/coulomb-loop)). Second loop
+[coulomb-loop](https://forgejo.coulomb.social/coulomb/coulomb-loop)). Second loop
 engagements should copy [customer-engagement-repo-layout.md](customer-engagement-repo-layout.md)
 and complete the checklist in one session.

@ -93,7 +93,7 @@ kaizen-agentic schedule init --engagement <slug> --bootstrap-cadence weekly --fo

 ## Reference implementation

- Customer: [coulomb-loop INTENT](https://gitea.coulomb.social/coulomb/coulomb-loop/src/branch/main/INTENT.md)
+- Customer: [coulomb-loop INTENT](https://forgejo.coulomb.social/coulomb/coulomb-loop/src/branch/main/INTENT.md)
 - Supplier workplan: [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md)
 - Convention: [ADR-006](../adr/ADR-006-customer-engagement-convention.md)

--- a/docs/integrations/customer-engagement-repo-layout.md
+++ b/docs/integrations/customer-engagement-repo-layout.md
@ -2,7 +2,7 @@

 Contract for a **customer engagement repository** that orchestrates kaizen
 improvement loops across a fleet roster. Reference implementation:
-[coulomb-loop](https://gitea.coulomb.social/coulomb/coulomb-loop) (`coulomb_social` domain).
+[coulomb-loop](https://forgejo.coulomb.social/coulomb/coulomb-loop) (`coulomb_social` domain).

 Supplier agents and CLI live in `kaizen-agentic`. Runtime `.kaizen/` state lives
 in **target repos**, not in the customer repo.