railiance-forge/SCOPE.md

SCOPE

This file defines what railiance-forge owns, when to use it, and where its boundaries stop.

Last reviewed: 2026-10-18

---

One-liner

Forge and artifact infrastructure for Railiance: current Forgejo operation (migrated from Gitea), container and package registries, Actions runner substrate, artifact lifecycle, and forge operational evidence.

---

Core Idea

railiance-forge separates forge responsibilities from S4 developer enablement and S5 application releases.

The practical contract is:

1. lower layers provide servers, Kubernetes runtime, databases, storage, and secret custody;
2. this repo owns the source forge runtime and artifact publication surface;
3. railiance-enablement owns reusable CI/CD templates and developer paved paths;
4. railiance-apps consumes forge artifacts and deploys user-facing workloads.

Canonical registry operation docs and read-only forge checks now live here. Deploy-capable forge Helm/SOPS/manifests also live here now; railiance-apps keeps only transitional compatibility wrappers for old operator entry points. The runner, Actions, and GitOps ownership contract lives in docs/ci-runner-actions-gitops-ownership.md. The backup, restore, and secret custody handoff contract lives in docs/backup-restore-secret-handoff.md. The observability and operating evidence contract lives in docs/observability-operating-evidence.md. The Fabric graph declarations for forge capabilities and edges live in /home/worsch/railiance-fabric/fabric/.

---

In Scope

• Current Forgejo operation (migrated from Gitea) and future forge change planning.
• Source forge deployment configuration and runbooks.
• Container registry and package registry enablement.
• Registry storage posture, cleanup, retention, and restore readiness.
• Forge-backed Actions runner substrate:
  • runner deployment ownership;
  • runner labels and placement;
  • runner credential and secret-access boundaries.
• Artifact publication evidence used by downstream release workflows:
  • image tags;
  • package versions;
  • commit SHA provenance;
  • promotion and smoke evidence.
• Forge observability and operator checks:
  • web endpoint health;
  • Git SSH health;
  • registry/package endpoint health;
  • runner health;
  • storage growth inspection.
• Fabric declarations for forge capabilities, interfaces, and dependencies.
• Repo-local workplan files under workplans/.

---

Out of Scope

• OS provisioning and host hardening: railiance-infra.
• Kubernetes runtime primitives, ingress controllers, and cluster addon installation: railiance-cluster.
• Shared databases, object storage, caches, and runtime secret custody: railiance-platform.
• Generic CI/CD templates, SDKs, buildpacks, and developer portal surfaces: railiance-enablement.
• User-facing application release charts, app runbooks, migrations, and smoke tests: railiance-apps.
• Application source code, package metadata, and image build definitions in source repos.
• Secret value custody. This repo may reference secret names and approved delivery paths, but it must not commit decrypted secret material.

---

Relevant When

• Operating or upgrading Forgejo as the current Railiance forge.
• Planning or executing a forge upgrade, migration or cutover.
• Enabling or debugging container/package registry behavior.
• Defining artifact retention, cleanup, provenance, or restore posture.
• Deploying or operating forge-backed Actions runners.
• Deciding whether a workflow issue is runner substrate, reusable template, or app-specific release logic.
• Declaring forge capabilities in Railiance Fabric.

---

Not Relevant When

• The work is an application release chart or app-specific runbook.
• The work is a generic workload template or SDK.
• The work is platform database provisioning or object-storage operation.
• The work is Kubernetes runtime installation or ingress controller ownership.
• The work is application source-code behavior.
• The work requires live secret values outside approved custody paths.

---

Current State

• Status: active forge operation with explicit S4 consumer-contract handoff.
• Implementation: repository contract, registry docs, initial operating contracts, deploy-capable forge files, and operator targets are present.
• Stability: emerging but now live-facing; forge owns the reviewed public Forgejo HTTPS ingress for the web UI, package registry, and OCI registry. Raw node IP HTTP access is not part of the supported forge surface.
• Usage: canonical operational reference for forge, registry, runner, retention, recovery, and resource evidence. S4 owns reusable consumer templates; this repo remains their provider and does not duplicate those templates.

Known starting point:

• railiance-forge owns forge Helm values, registry overlays, public HTTPS ingress, operating contracts, and deploy/status entry points.
• railiance-apps keeps app release ownership and transitional compatibility wrappers for old Gitea commands.
• railiance-enablement owns delivery templates and developer paved paths, but not forge runtime, registry, runner, retention, or recovery operation.
• railiance-forge should absorb forge runtime and artifact infrastructure without moving S5 app release ownership.

---

How It Fits

• Upstream dependencies: railiance-infra, railiance-cluster, and railiance-platform.
• Adjacent collaborators: railiance-enablement for reusable CI/CD paths and railiance-apps for consuming release artifacts in app deployments.
• Downstream consumers: source repos, app release repos, operators, and Railiance users relying on source hosting and published artifacts.

---

Terminology

• Preferred terms: forge, source forge, artifact registry, package registry, runner substrate, release evidence.
• Also known as: Gitea/Forgejo operations, release infrastructure.
• Potentially confusing terms: "workflow template" belongs in S4 enablement; "runner substrate" belongs here; "app release workflow" belongs near the app or S5 release surface.

---

Related / Overlapping

• railiance-apps - consumes forge artifacts in S5 app releases and keeps transitional pointers/wrappers for old Gitea paths.
• railiance-enablement - owns reusable CI/CD templates, SDKs, buildpacks, and developer portal paths.
• railiance-platform - provides database, storage, backup, and runtime secret services consumed by forge workloads.
• railiance-cluster - provides Kubernetes runtime and cluster-level addons.
• railiance-fabric - should model forge capabilities, interfaces, providers, and consumers.

---

Getting Oriented

1. Read AGENTS.md for session protocol and State Hub conventions.
2. Read INTENT.md for stable purpose.
3. Read this file for scope and boundaries.
4. Read active files in workplans/.
5. For registry operations, read docs/gitea-container-registry.md and docs/gitea-package-registry.md.
6. For runner, Actions, and GitOps ownership, read docs/ci-runner-actions-gitops-ownership.md.
7. For backup, restore, and secret custody handoffs, read docs/backup-restore-secret-handoff.md.
8. For observability and release-readiness evidence, read docs/observability-operating-evidence.md.
9. For Fabric graph declarations, read /home/worsch/railiance-fabric/fabric/ and query them with railiance-fabric.
10. For migration context, read /home/worsch/railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md.

---

Provided Capabilities

type: infrastructure
title: Railiance source forge operation
description: Operate the current Forgejo source forge (migrated from Gitea) and plan future forge changes as dedicated Railiance forge infrastructure.
keywords: [railiance, forge, gitea, forgejo, source-hosting, git]

type: infrastructure
title: Railiance artifact registry operation
description: Own container and package registry enablement, retention, restore posture, and release artifact evidence for Railiance consumers.
keywords: [registry, container-image, python-package, artifact, retention, provenance]

type: operations
title: Forge automation runner substrate
description: Define and operate forge-backed runner infrastructure, runner labels, runner placement, and credential boundaries used by CI/CD workflows.
keywords: [actions, runner, ci, gitops, automation, credentials]

type: operations
title: Forge resource economics observation
description: Capture non-secret forge requests, observed utilization, storage, runner and recovery evidence with make forge-observe REMOTE=railiance01. Timestamped observations support resource-control; unknown objectives and unattributed consumption remain explicit. No public economics endpoint is provided.
keywords: [forgejo, runner, capacity, utilization, storage, allocation, evidence]

Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through .generated-work-records.json and the isolated .generated-work-records.mk recipe. make generated-work-records reuses the State Hub renderer through the Custodian adapter; make generated-work-records-check verifies byte-exact agreement with staged Markdown. The pre-commit hook uses the isolated recipe, preserves unstaged index edits by refusing them, and retains the generated-only commit guard and existing security checks. It does not contact the hub, alter workplan statuses or grant deployment authority. This consumes shared tooling; it does not make this repository the provider of the generator capability.

Local orientation brief policy — 2026-10-19

.custodian-brief.md is a local, ignored State Hub orientation snapshot. Its existing bytes remain available for offline session startup; refreshing it does not require a Git commit. Authored workplans and the generated WORK-RECORDS index retain their existing source and staged-generation contracts. No runtime or credential change follows from this repository hygiene policy.