kaizen-agentic/workplans/KAIZEN-WP-0010-forgejo-pypi-migration.md

---
id: KAIZEN-WP-0010
type: workplan
title: "Migrate package distribution from gitea to forgejo before CoulombCore retires"
domain: agents
repo: kaizen-agentic
status: finished
owner: kaizen-agentic
topic_slug: custodian
created: "2026-08-20"
updated: "2026-08-20"
depends_on: []
tasks:
  - id: T01
    status: done
    title: Establish whether kaizen-agentic packages already exist on forgejo
  - id: T02
    status: done
    title: Publish current versions to the forgejo PyPI index
  - id: T03
    status: done
    title: Repoint Makefile and all six docs in one change
  - id: T04
    status: done
    title: Verify a clean install from forgejo on an uncached machine
  - id: T05
    status: done
    title: Retire the gitea variables and close out
state_hub_workstream_id: "ade14e03-98d8-5d0b-88d7-f7774114f050"
---

# KAIZEN-WP-0010 — Migrate package distribution to forgejo

**Deadline: 2026-08-31.** Not a target — CoulombCore is being decommissioned by
the operator on that date.

## Why this exists

`gitea.coulomb.social` runs on CoulombCore and serves two things: a container
registry and a **PyPI package index** at `/api/packages/coulomb/pypi`. Both stop
existing when the host does.

kaizen-agentic's release workflow moved to Forgejo in early July, but the
Makefile, consumer documentation, issue links, templates, and capability
metadata did not move with it. This left a split-brain distribution story even
though the destination already existed and was in use.

### What breaks, and why it is worse than a broken link

```
Makefile:10   GITEA_PYPI_REPOSITORY_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi
Makefile:11   GITEA_PYPI_SIMPLE_URL     ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi/simple/
```

and the install instructions in **six** documents — `README.md`,
`docs/GETTING_STARTED.md`, `docs/AGENT_DISTRIBUTION.md`,
`docs/PACKAGE_RELEASE.md`, `docs/HELLO_WORLD_TUTORIAL.md`,
`docs/CLI_CHEAT_SHEET.md` — all tell users to
`pip install --extra-index-url …@gitea.coulomb.social/api/packages/coulomb/pypi/simple/`.

These are the documented install instructions for the kaizen agent
distribution. After 2026-08-31 every one fails, and it fails *looking like a
broken package* rather than a retired host — so the person hitting it will debug
the wrong thing.

## The one rule for sequencing

**Publish before you repoint.** A registry migration is not a find-and-replace.
If the docs change first, they point at a 404 instead of a soon-to-be-404, which
is strictly worse: today's instructions at least work. T01 and T02 come before
T03, and T03 is a single change covering the Makefile and all six documents
together — a half-migrated doc set is how the next repo gets missed.

## Tasks

```task
id: KAIZEN-WP-0010-T01
status: done
priority: high
state_hub_task_id: "63acba1a-f8e5-584d-9a85-b5e599e23681"
```

**Establish whether kaizen-agentic packages already exist on forgejo.** Check
`forgejo.coulomb.social/api/packages/coulomb/pypi` for current package names and
versions. This is a read; do not publish yet.

Record what is there against what gitea holds. If forgejo already has current
versions, T02 becomes a no-op and this finishes much faster than feared — worth
five minutes before assuming a full republication.

**Result (2026-08-20):** Forgejo anonymously serves the current `1.4.0` wheel
and sdist. Gitea serves `1.1.0`, `1.2.0`, and `1.4.0`. The repository version
and latest tag are both `1.4.0`.

The simple package index is anonymously readable. If a write or authenticated
API inventory is ever needed, route the Forgejo credential through `warden`
and never paste a token into the Makefile or documentation.

```task
id: KAIZEN-WP-0010-T02
status: done
priority: high
state_hub_task_id: "51ef8a2f-880e-5c93-ac88-c2468453f391"
```

**Publish current versions to the forgejo PyPI index.** Only the versions that
matter — whatever the docs tell users to install, plus the current release.
Historical versions are a judgement call: republish them only if something
actually pins an old version.

`issue-core/Makefile:250` is a working example of the forgejo `twine upload`
target and is the shortest path to a correct invocation.

**Result (2026-08-20):** No-op. The current `1.4.0` release was already on
Forgejo, published by `.forgejo/workflows/publish-python-package.yml`; no
credential request or duplicate upload was necessary.

```task
id: KAIZEN-WP-0010-T03
status: done
priority: high
state_hub_task_id: "db50966e-1f3b-5fc0-ad8f-ea55f9b2f881"
```

**Repoint the Makefile and all six docs in one change.** Add
`FORGEJO_PYPI_REPOSITORY_URL` / `FORGEJO_PYPI_SIMPLE_URL` and make them the
default path, then update every install instruction listed above.

Decide deliberately whether to keep the gitea variables temporarily for
comparison or delete them now. `issue-core` kept both and now carries a legacy
target that fails after 08-31 — a trap for whoever runs the wrong `make`. Given
the deadline is nine days after this workplan is written, deleting outright is
probably the better call here, but make it a decision rather than a default.

Also update `GITEA_PACKAGE_USER` / `GITEA_PACKAGE_TOKEN` variable *names* if you
keep the credential envelope — a variable called `GITEA_*` pointing at forgejo is
the kind of thing that survives for years and confuses everyone who reads it.

**Result (2026-08-20):** Removed the Gitea Make variables and target outright;
`publish-forgejo` and `FORGEJO_PYPI_*` are the only release path. Consumer
instructions now use the anonymously readable Forgejo index without embedding
unnecessary credentials. Updated the six named documents plus operational
references in contributing/scope/capability metadata, CLI feedback URLs, issue
templates, project metadata, and packaged agent guidance.

```task
id: KAIZEN-WP-0010-T04
status: done
priority: high
state_hub_task_id: "2db93b97-62c6-539b-b0a1-471dd0767014"
```

**Verify a clean install from forgejo on a machine with no cache.** A `pip
install` that succeeds because the wheel is already in a local cache proves
nothing. Use a fresh venv and `--no-cache-dir`, following the README's own
instructions verbatim — if the documented command does not work, the docs are
still wrong regardless of what the registry holds.

This is the task that actually closes the risk. T01–T03 are preparation.

**Result (2026-08-20):** A new temporary virtual environment installed
`kaizen-agentic==1.4.0` with `--no-cache-dir` and the documented anonymous
Forgejo extra index. Pip downloaded the wheel from Forgejo; both the CLI and
Python package reported `1.4.0`.

```task
id: KAIZEN-WP-0010-T05
status: done
priority: medium
state_hub_task_id: "36e9d767-c4f9-57f2-9be4-8e474d8aab11"
```

**Close out.** Remove any remaining gitea references from operational files
(`Makefile`, docs, CI). Leave alone anything that merely *records* that gitea
existed — history stays true after the host is switched off, and rewriting it to
tidy a grep loses information.

Tell `prj-state-hub-retirement` when T04 passes; this is tracked there as
`SHR-WP-0002-T07` and is one of two items gating CoulombCore's retirement.

**Result (2026-08-20):** No CoulombCore/Gitea host, package variable, publish
target, workflow path, or issue-template path remains in operational files.
Historical workplans and changelog entries were deliberately preserved.

## Notes

- Drafted by `prj-state-hub-retirement` on 2026-08-20 from the estate-wide sweep
  that found this repo. The sequencing rule and the deadline are ours; **the
  packaging decisions are yours** — nothing here has been applied to your files.
- If any of this is wrong about how kaizen-agentic actually publishes, trust
  your own knowledge and tell the project. The sweep read your Makefile and
  docs; it did not run your release process.