--- id: KAIZEN-WP-0010 type: workplan title: "Migrate package distribution from gitea to forgejo before CoulombCore retires" domain: agents repo: kaizen-agentic status: proposed owner: kaizen-agentic topic_slug: custodian created: "2026-08-20" updated: "2026-08-20" depends_on: [] tasks: - id: T01 status: todo title: Establish whether kaizen-agentic packages already exist on forgejo - id: T02 status: todo title: Publish current versions to the forgejo PyPI index - id: T03 status: todo title: Repoint Makefile and all six docs in one change - id: T04 status: todo title: Verify a clean install from forgejo on an uncached machine - id: T05 status: todo title: Retire the gitea variables and close out --- # 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 appears to be the only repo in the estate that never migrated. The rest moved in early July — `issue-core` carries both endpoints (`Makefile:68` gitea, `Makefile:69` forgejo, publish targets at `240` and `250`), and `vergabe-teilnahme/pyproject.toml` already points at `forgejo.coulomb.social/api/packages/coulomb/pypi/simple/`. So the destination exists and is in use; this repo was missed. ### 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: todo priority: high ``` **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. Credentials: this needs a forgejo package token, not a gitea one. Route through `warden plan "forgejo package publish token"` rather than reusing `GITEA_PACKAGE_TOKEN`, and never paste a token into the Makefile or a doc. ```task id: KAIZEN-WP-0010-T02 status: todo priority: high ``` **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. ```task id: KAIZEN-WP-0010-T03 status: todo priority: high ``` **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. ```task id: KAIZEN-WP-0010-T04 status: todo priority: high ``` **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. ```task id: KAIZEN-WP-0010-T05 status: todo priority: medium ``` **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. ## 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.