Canonicalize registry docs and read-only ops

docs/first-migration-plan.md

@@ -2,6 +2,9 @@
 
 Date: 2026-06-05
 
+Status: Phase 1 is underway. The remote repository exists and is pushed, so the
+earlier Gitea API blocker no longer applies.
+
 This plan starts the extraction of forge ownership from `railiance-apps` into
 `railiance-forge` without changing the live Gitea deployment.
 
@@ -85,7 +88,7 @@ Review gates:
 
 - `railiance-forge` remote exists and is pushed.
 - State Hub workplans are synced in both repos.
-- Operator confirms the Gitea token/remote creation issue is fixed.
+- Operator confirms deploy-capable Gitea ownership should move now.
 - `railiance-apps` has compatibility pointers for old paths.
 - The plan distinguishes current Gitea operation from future Forgejo cutover.
 
@@ -112,19 +115,13 @@ Validation:
 - `railiance-apps` no longer claims forge runtime ownership.
 - App operators can still find registry instructions through pointers.
 
-## Open Blocker
+## Remote Status
 
-The local `tea` login named `coulomb` is configured but currently fails with
-`invalid username, password or token`. This blocks creation of the remote
-`coulomb/railiance-forge` repository through the Gitea API.
-
-Until refreshed credentials are available:
-
-- keep `railiance-forge` local and State Hub-registered;
-- do not add an `origin` remote that points to a missing repository;
-- avoid claiming remote publication is complete.
+`railiance-forge` now has `origin` configured as
+`gitea-remote:coulomb/railiance-forge.git` and the local `main` branch is
+aligned with `origin/main`.
 
 ## Next Recommended Action
 
-Proceed with Phase 1 documentation canonicalization after the operator confirms
-that compatibility pointers in `railiance-apps` are acceptable.
+Complete Phase 1 documentation canonicalization and Phase 2 read-only operator
+targets, then review the deploy-capable Gitea file move separately.

docs/gitea-container-registry.md

@@ -0,0 +1,84 @@
+# Gitea Container Registry
+
+This is the canonical Railiance operating note for the current Gitea container
+registry. Compatibility pointers remain in `railiance-apps` while deploy-capable
+Gitea Helm and manifest files still live there.
+
+## Registry Target
+
+Use `gitea.coulomb.social` as the approved registry host. The `/v2` ingress is
+live as of 2026-05-15 and returns the OCI registry authentication challenge over
+HTTPS.
+
+Registry-specific Gitea settings are currently carried in
+`/home/worsch/railiance-apps/helm/gitea-registry-values.yaml`, a non-secret
+overlay applied after the SOPS values file by `make gitea-deploy`. It explicitly
+enables packages, permits container and PyPI uploads without an app-level size
+cap, clears globally disabled repo units, and moves `ROOT_URL` to the HTTPS
+host.
+
+Image names should use the Gitea owner and package path:
+
+```bash
+gitea.coulomb.social/coulomb/state-hub:<tag>
+```
+
+The State Hub handoff from `CUST-WP-0011` should publish the locally verified
+`state-hub:local` image under that name.
+
+The successful smoke-test tags were:
+
+```bash
+gitea.coulomb.social/coulomb/state-hub:6186a99
+gitea.coulomb.social/coulomb/state-hub:latest
+```
+
+Digest:
+
+```text
+sha256:039d29654ccb3754c6ecdbe497c6364bbd8452edcdcb7fa937dd9debf5b734ff
+```
+
+## Operator Smoke Test
+
+Use a Gitea personal access token with package read/write permission:
+
+```bash
+docker login gitea.coulomb.social
+docker tag state-hub:local gitea.coulomb.social/coulomb/state-hub:<tag>
+docker push gitea.coulomb.social/coulomb/state-hub:<tag>
+docker pull gitea.coulomb.social/coulomb/state-hub:<tag>
+```
+
+The `coulomb` organization packages are public by default, so the verified
+cluster pull for `state-hub:6186a99` did not require an `imagePullSecret`.
+
+For private packages, create an image pull secret in each consuming namespace:
+
+```bash
+kubectl create secret docker-registry gitea-registry \
+  --docker-server=gitea.coulomb.social \
+  --docker-username=<gitea-user> \
+  --docker-password=<package-token> \
+  --namespace=<namespace>
+```
+
+Reference it from workloads as `imagePullSecrets: [{name: gitea-registry}]`.
+
+## Python Packages
+
+The same Gitea package service is used for Python wheels. See
+`docs/gitea-package-registry.md` for the publish/install recipe and the
+`issue-core` migration notes from `RAILIANCE-WP-0004 I03`.
+
+## Current Storage Notes
+
+The live Gitea pod mounts `gitea-shared-storage` at `/data`; package blobs land
+under `/data/packages`. On 2026-05-19 that package directory was about
+798.5 MiB.
+
+The PVC is `default/gitea-shared-storage`, 10 GiB, `local-path`, `RWO`. The live
+cluster showed no Kubernetes `CronJob` backup resources across namespaces on
+2026-05-19. This is acceptable for the current smoke-test images, but heavy tag
+growth should wait for the forge/platform backup and retention follow-up in
+`docs/initial-operating-contracts.md`.

docs/gitea-package-registry.md

@@ -0,0 +1,50 @@
+# Gitea Package Registry
+
+This is the canonical Railiance operating note for the current Gitea Python
+package registry. Compatibility pointers remain in `railiance-apps` while
+deploy-capable Gitea Helm and manifest files still live there.
+
+Gitea package support is enabled by
+`/home/worsch/railiance-apps/helm/gitea-registry-values.yaml`. That overlay is
+applied after the encrypted base values by `make gitea-deploy` and enables both
+container packages and Python packages.
+
+## Python Packages
+
+Publish Python wheels to the organization package endpoint:
+
+```bash
+python -m build
+TWINE_USERNAME=<gitea-user> \
+TWINE_PASSWORD=<package-token> \
+python -m twine upload \
+  --repository-url https://gitea.coulomb.social/api/packages/coulomb/pypi \
+  dist/*
+```
+
+Install from the simple index:
+
+```bash
+pip install \
+  --extra-index-url https://<gitea-user>:<package-token>@gitea.coulomb.social/api/packages/coulomb/pypi/simple/ \
+  issue-core
+```
+
+For CI, store the token as a secret and inject it into the package index URL at
+build time. Do not commit tokenized index URLs.
+
+## issue-core Migration
+
+The portable deployment path for `vergabe-teilnahme` is:
+
+1. Release `issue-core` from its source repo as a wheel, for example `0.2.0`.
+2. Publish the wheel to the Gitea Python package registry.
+3. Keep `vergabe-teilnahme/pyproject.toml` on a versioned dependency such as
+   `issue-core>=0.2,<0.3`.
+4. Regenerate `vergabe-teilnahme/uv.lock` from the Gitea PyPI registry after the
+   package exists there.
+5. Build the image on a clean runner that has no sibling `issue-core` checkout.
+
+Registry endpoint ownership lives in `railiance-forge`; the package release and
+application dependency lock belong to the `issue-core` and `vergabe-teilnahme`
+source repos.

docs/initial-operating-contracts.md

@@ -0,0 +1,89 @@
+# Initial Forge Operating Contracts
+
+Last reviewed: 2026-06-05
+
+These contracts are the first explicit boundary for the Railiance forge layer.
+They are intentionally operational enough to guide the next file moves, while
+leaving live deploy and secret custody changes behind separate review gates.
+
+## Status
+
+- Contract maturity: draft v1.
+- Live impact: none; this document does not authorize a deploy or cutover.
+- Current forge runtime: Gitea at `gitea.coulomb.social`.
+- Future migration target: Forgejo, under a separate cutover workplan.
+
+## Artifact Lifecycle And Provenance
+
+- Source repositories own build definitions, package metadata, and release
+  versioning.
+- `railiance-forge` owns the registry endpoints, registry operating docs,
+  retention posture, and artifact evidence model.
+- `railiance-apps` consumes already-published artifacts in S5 release values and
+  runbooks.
+- Container images should publish immutable commit-SHA tags for release
+  evidence. Mutable tags such as `latest` are allowed only as convenience
+  pointers and must not be the sole production reference.
+- Python packages should use versioned releases. Internal consumers should pin
+  compatible ranges in source repos and regenerate locks after the package is
+  published.
+- Release evidence should capture source repo, commit SHA, artifact name,
+  version/tag, smoke result, and consuming deployment value change.
+
+## Retention And Cleanup
+
+- Smoke-test image tags can be pruned after a newer validated smoke tag exists
+  and no rollback or diagnosis still references them.
+- Production image tags and Python package versions should be retained for at
+  least the active rollback window of every consuming deployment.
+- Deleting a package or image is an operator action, not an automated default,
+  until package restore has been drilled.
+- The current Gitea package data lives under `/data/packages` on the
+  `default/gitea-shared-storage` PVC. On 2026-05-19 it was about 798.5 MiB of a
+  10 GiB `local-path` volume.
+- Growth inspection belongs in forge operations; durable backup implementation
+  belongs with the platform storage/database layer.
+
+## Runner Substrate Ownership
+
+- `railiance-forge` owns Gitea/Forgejo Actions runner deployment, runner labels,
+  runner placement, runner credentials, and runner health evidence.
+- `railiance-enablement` owns reusable workflow templates, paved paths, and
+  developer-facing automation conventions.
+- Application repos own app-specific workflows and build scripts.
+- `railiance-apps` owns S5 release checks for app manifests and deployment
+  values, but not the runner substrate those checks execute on.
+- Runner secret access must be explicit by label, repository, and workflow
+  purpose. Broad package or cluster credentials should not be shared across
+  unrelated jobs.
+
+## Backup And Restore Handoff
+
+- `railiance-forge` defines what must be restorable: Git repositories, package
+  blobs, registry metadata, runner configuration, and source-forge application
+  state.
+- `railiance-platform` owns the reusable database, object-storage, backup, and
+  restore mechanisms used by forge workloads.
+- Forge data should not become production-critical without a recorded restore
+  drill for the relevant storage path.
+- S5 app releases may consume forge artifacts, but they should cite forge
+  evidence rather than owning package blob backup procedures themselves.
+
+## Secret Custody
+
+- This repo may reference secret names, SOPS file paths, OpenBao paths, and
+  operator procedures.
+- This repo must not commit decrypted secret values, package tokens, runner
+  tokens, tokenized package index URLs, or generated credential material.
+- Deploy-capable files that reference encrypted values move only after review of
+  the SOPS/OpenBao handoff and compatibility pointers.
+
+## Observability And Evidence
+
+- `make gitea-status` is the first read-only operator check in this repo.
+- Forge health should cover web, Git SSH, container registry, Python package
+  registry, database, package storage, and runner status.
+- Downstream app release evidence should cite forge artifact evidence rather
+  than repeating registry implementation details.
+- Future monitoring should turn the manual status checks into durable signals
+  once the Railiance observability layer is ready.