# INTENT

> This file captures **why this repository exists**,
> the **direction it is moving toward**, and
> the **kind of system it is meant to become**.
> It is intentionally **aspirational and stable**, not a description of current implementation.

---

## One-liner

**The forge layer - turning source hosting, registries, and automation runners into dependable Railiance release infrastructure.**

---

## Why This Exists

Applications need more than a runtime to ship safely. They need a governed
place for source hosting, package and image publication, CI runner substrate,
release artifact retention, and operational evidence.

Before this repo, forge concerns were spread across S4 enablement and S5
application deployment work. That made it hard to tell who owned Gitea,
Forgejo, package registries, Actions runners, registry storage, and artifact
promotion evidence.

This layer exists to make those responsibilities explicit and operable.

---

## The Mission

> *Where we are going.*

To become the **canonical home for Railiance forge and artifact infrastructure**
- current Gitea operation, future Forgejo migration, container and package
registries, forge-backed automation runner substrate, artifact lifecycle, and
forge operational evidence.

This means:

* Source forge runtime is operated through a clear repo-owned contract
* Package and image registries have retention, restore, and capacity posture
* CI runners are owned separately from reusable CI/CD templates
* S5 applications can consume artifacts without owning forge internals
* Future Forgejo cutover can happen without confusing it with app deployment

---

## Core Principles

### 1. Forge Runtime, Not Application Releases

Own the forge and artifact infrastructure. Do not own user-facing application
release charts or application source code.

### 2. Artifacts With Evidence

Images, packages, and release assets should carry enough provenance and
inspection evidence for downstream releases to trust them.

### 3. Runner Substrate, Not Every Workflow

Own the runner infrastructure and credentials. Reusable workflow templates
belong in S4 enablement, and app-specific workflows belong near the app or its
release repo.

### 4. Stable Handoffs

Consumers should depend on stable forge capabilities: source hosting, Git SSH,
container registry, package registry, workflow execution, and artifact
promotion evidence.

### 5. Restore Before Trust

Forge data is operationally critical. Source repos, packages, registry blobs,
and runner state need explicit backup and restore posture.

### 6. Current Gitea, Future Forgejo

Gitea is the current workload; Forgejo is the intended production direction.
The repo should support both the current operating state and clean future
cutover planning.

---

## What This Is (Conceptually)

This layer is:

* a **source forge operations** layer
* an **artifact registry** layer
* an **automation runner substrate** layer
* a **release evidence** provider
* a bridge between S4 delivery paths and S5 application releases

---

## What This Is Not

This layer is not:

* the infrastructure substrate beneath Railiance
* the Kubernetes runtime
* the shared platform-services layer
* the generic CI/CD template and developer portal layer
* the application release and runbook layer
* the source-code home for business applications
* a runtime secret custody authority

It is the forge and artifact infrastructure that lets the rest of Railiance
build, publish, automate, and consume releases.

---

## Direction of Evolution

This layer is expected to evolve toward:

* Clean extraction of current Gitea operation from `railiance-apps`
* Explicit Forgejo migration and production cutover planning
* Versioned artifact lifecycle and retention policy
* Runner placement, label, credential, and secret-access policy
* Backup and restore evidence for source, package, and registry data
* Fabric declarations for forge capabilities and dependencies
* Self-evidencing forge health and readiness checks

---

## Guiding Question

> **How can Railiance make source hosting, artifact publication, and automation execution dependable enough that application releases can consume them without owning them?**