seeded repo

INTENT.md

@@ -0,0 +1,132 @@
+# 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?**